---
title: "Push Event Webhook"
slug: "push-event-webhook"
updated: 2026-09-24T19:06:02Z
published: 2026-09-24T19:06:10Z
canonical: "docs.relaynetwork.com/push-event-webhook"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relaynetwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

![](https://cdn.us.document360.io/6738087b-455d-402f-b70a-a44a4231547e/Images/Documentation/image.png)

## Event Properties

| Legend | Areas of Control | Events |
| --- | --- | --- |
| Client Controlled | Input Data |  |
| Relay Controlled | Connection Management, Feed Message Delivery, SMS Notification requests to Kaleyra | account.deactivate channel_consent.update notification_channel.add notification_channel.remove message.delivered message.undelivered notification.attempted notification.not_attempted |
| SMS Aggregator Controlled | SMS Notification requests to Carrier Delivery receipts from Carriers to Relay | notification.delivered notification.undelivered |
| Customer Controlled | Auth Links clicked Actions Taken | notification.auth_link_clicked message.action_taken |

## 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.

> [!CAUTION]
> 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.

> [!CAUTION]
> 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.

> Relay does not support any API endpoints using the default AWS API Gateway hostnames such as *.execute-api.<region>.amazonaws.com. These hostnames can be automatically overridden by private AWS networking (PrivateLink/Private DNS) when both parties operate in the same AWS region, causing your API to resolve to **private, unreachable IP addresses**. To ensure reliable connectivity, all public-facing APIs must be served through a **custom domain name** (e.g., api.yourcompany.com) that resolves to the **public** API Gateway domain provided during your custom domain setup. Using a custom domain avoids AWS’s internal DNS overrides and guarantees that our systems can reach your API successfully. AWS Reference Documentation: [https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html)

## Authentication

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

### Basic auth

```json
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

```json
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

```json
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

```json
{
    "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:

> [!TIP]
> 200
> 
> Success, the event payload was accepted. While you can provide information in the body Relay will not process it in any way.

> [!WARNING]
> 401
> 
> Invalid access. This can occur if the authentication is not properly configured.

> [!CAUTION]
> 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

> [!CAUTION]
> 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