Push Event Webhook

Overview

Webhooks are used by Relay to inform your system of events that are taking place within the Relay platform. Example events include SMS events, click-throughs, mobile consent changes (e.g. stops) and when an end-user engages on the Relay Feed just to name a few.

When an event occurs, Relay will make an HTTPS POST call to the Webhook URL you have configured. The HTTPS request will include the details of the event that occurred.

The Relay Webhook supports single event transactions (one per HTTPS call).

SAMPLE EVENT FLOW

Event Properties

Event Ordering

Do to the nature of the system, it is possible for events to arrive slightly out of order. For example you may receive a notification.undelivered event before the 'notification.attempted' event. However, event timestamp, in the event_ts field, is accurate and can be used in any processing logic.

Do not assume events will arrive in exact time stamp order.

Do not assume events will arrive in a logical progression order.

Filtering Events

The Relay system emits a large number of different event types. The webhook can be configured to only send events you are interested in.

Implementation

To receive the webhook events from Relay, you must implement a minimal web endpoint that can accept HTTPS requests.

The webhook must be exposed over an HTTPS endpoint leveraging TLS 1.2+. Relay will not attempt to call the webhook over an insecure HTTP connection.

Authentication

The Relay webhook system supports the following types of authentication using standard best practices:

Basic auth

curl --location --request POST '$CUSTOM_ENDPOINT' \
--header 'Authorization: basic $BASE64_AUTH_STRING' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_id": "ip-10-3-0-224-668176-8h-b98185e8-8a01-406f-a9e9-a62a2e437da7-1mha",
    "event_ts": "2022-04-12T14:53:11.958Z",
    "payload": {
        "action_type": null,
        "product_group_id": "default",
        "trigger_id": "91c08533-3ebe-49e3-a44a-4d885744feaf",
        "channel_addr": "",
        "channel_type": "",
        "ccid": "relay_pushAPI_customer",
        "journey_id": "ee0af7fa-e278-4bbb-83b6-b04cf6612e04",
        "action_value": null,
        "relay_tracking_id": "6d5d4d44-3982-456f-b694-7ce39b229889",
        "message_id": "43244abd-45dc-4b27-8682-54337554c876",
        "message_name": "Relay Push API Message",
        "notification_id": null,
        "action_label": null,
        "client_id": "relay_push_api_sample",
        "event_type": "message",
        "client_message_tag": "",
        "job_id": "6f7970db-6040-4fb2-80e1-f43646e9e75e",
        "customer_id": "325030d6-8135-4e55-82b3-272eab6e77e3",
        "event_subtype": "delivered"
    },
    "event_name": "message.delivered"
}'

API key

curl --location --request POST '$CUSTOM_ENDPOINT' \
--header 'Content-Type: application/json' \
--header 'ApiKey: $API_KEY' \
--data-raw '{
    "event_id": "ip-10-3-0-224-668176-8h-b98185e8-8a01-406f-a9e9-a62a2e437da7-1mha",
    "event_ts": "2022-04-12T14:53:11.958Z",
    "payload": {
        "action_type": null,
        "product_group_id": "default",
        "trigger_id": "91c08533-3ebe-49e3-a44a-4d885744feaf",
        "channel_addr": "",
        "channel_type": "",
        "ccid": "relay_pushAPI_customer",
        "journey_id": "ee0af7fa-e278-4bbb-83b6-b04cf6612e04",
        "action_value": null,
        "relay_tracking_id": "6d5d4d44-3982-456f-b694-7ce39b229889",
        "message_id": "43244abd-45dc-4b27-8682-54337554c876",
        "message_name": "Relay Push API Message",
        "notification_id": null,
        "action_label": null,
        "client_id": "relay_push_api_sample",
        "event_type": "message",
        "client_message_tag": "",
        "job_id": "6f7970db-6040-4fb2-80e1-f43646e9e75e",
        "customer_id": "325030d6-8135-4e55-82b3-272eab6e77e3",
        "event_subtype": "delivered"
    },
    "event_name": "message.delivered"
}

Oauth - Client Credentials

curl --location --request POST '$CUSTOM_ENDPOINT' \
--header 'Content-Type: application/json' \
--header 'Authorization: $BEARER_TOKEN' \
--data-raw '{
    "event_id": "ip-10-3-0-224-668176-8h-b98185e8-8a01-406f-a9e9-a62a2e437da7-1mha",
    "event_ts": "2022-04-12T14:53:11.958Z",
    "payload": {
        "action_type": null,
        "product_group_id": "default",
        "trigger_id": "91c08533-3ebe-49e3-a44a-4d885744feaf",
        "channel_addr": "",
        "channel_type": "",
        "ccid": "relay_pushAPI_customer",
        "journey_id": "ee0af7fa-e278-4bbb-83b6-b04cf6612e04",
        "action_value": null,
        "relay_tracking_id": "6d5d4d44-3982-456f-b694-7ce39b229889",
        "message_id": "43244abd-45dc-4b27-8682-54337554c876",
        "message_name": "Relay Push API Message",
        "notification_id": null,
        "action_label": null,
        "client_id": "relay_push_api_sample",
        "event_type": "message",
        "client_message_tag": "",
        "job_id": "6f7970db-6040-4fb2-80e1-f43646e9e75e",
        "customer_id": "325030d6-8135-4e55-82b3-272eab6e77e3",
        "event_subtype": "delivered"
    },
    "event_name": "message.delivered"
}'

Individual Event Processing

Example Individual Event Payload

{
    "event_id": "4378439B-1D30-4405-ABE0-BF7F338F3788",
    "event_name": "notification.auth_link_used",
    "event_ts": "2021-04-14T12:00:00.000Z",
    "payload": {
        "ccid": "1002",
        "client_id": "acme_corp",
        "client_message_tag": "",
        "channel_addr": "10005552222",
        "channel_type": "sms",
        "customer_id": "9006E214-5261-4736-9192-B0ADD3005723",
        "job_id": "A689672A-0A6E-4E99-8C5D-1CAD3728CA32",
        "journey_id": "44BE6B5D-26B1-40EA-9750-2E8C82067AF6",
        "message_id": "F0920F03-8D38-4C7B-A03A-14F47634E3D1",
        "message_name": "nickname",
        "notification_id": "2B7C306C-0F48-4F18-8F4D-205A00408E4D",
        "product_group_id": "default",
        "relay_tracking_id": "0AC9067B-D91A-4744-B8F6-6290B2DCCE6B",
        "trigger_id": "F9564106-C25A-4FD2-A9DF-F26ADC1D1362"
    }
}

Webhook Response

If the webhook is configured for batch processing then the response is related to the entire batch. Therefore, if a 200 is returned the entire batch is marked accepted and if a 500 is returned the entire batch is marked as error and the same batch will be retried.

The following webhook response codes are supported:

200

Success, the event payload was accepted. While you can provide information in the body Relay will not process it in any way.

401

Invalid access. This can occur if the authentication is not properly configured.

500

Service is down. Relay will retry the request as outlined in the Retry section below.

If your endpoint has a business or logic error while processing the request, do not respond to the webhook with a 400 as it will not be relevant to Relay. Instead you should log the error in your system, save the request body for your teams further analysis and return a 200 to Relay.

Scaling

When implementing the webhook interface it is important that your backend system can scale to handle the volume of events being emitted from the Relay system. Ensure your IT team, implementing the webhook, is informed on how the Relay system operates and what will trigger a webhook call.

For example, if you submit a large CSV file for processing with 1m records, Relay could start hitting the webhook at a rate of several thousands calls per minute - especially for the individual (non batch) requests.

If scaling is a concern, switching to the batch processing may be beneficial.

Retry Logic

In the event that the webhook returns a 500, or if the call to the webhook timeouts, Relay will a total of four attempts to send the event (with delays in-between each retry). If the fourth attempt fails, Relay will log the error and then move onto the next event. This will prevent a case where there is an issue processing the specific request and creating an endless loop of errors.

Schedule Webhook Maintenance

Webhook Downtime

If your webhook will be offline for any scheduled maintenance, please contact your Relay Client Success Manager and provide the date and times of when the webhook will be offline.If your webhook will be offline for any scheduled maintenance, please contact your Relay Client Success Manager and provide the date and times of when the webhook will be offline.

Whitelisting Relay IP Addresses for Webhook Events

This section documents the IP addresses that Relay uses when pushing data to clients leveraging the Push API Webhook. Clients can choose to whitelist to the IP addresses for each environment, although it is not required.

Relay Staging Environment

50.112.172.205

Relay Production Environment

52.73.72.6