Configure Webhooks for Message Delivery Events

Webhooks let RelayOS push delivery status updates to your server the moment they happen, instead of requiring you to poll GET /v1/messages/{id}. Each time a message changes status — sent, delivered, read, or failed — RelayOS sends an HTTP POST request to the callbackUrl you configure on your project. Your endpoint receives a JSON payload describing the event and can use it to update your database, trigger follow-up logic, or surface delivery confirmation to your users.

Configure your callback URL

Set your callbackUrl by calling PUT /v1/projects/me/meta-credentials. You can include it alongside your Meta credentials or update it on its own at any time.

curl -X PUT https://api.relayos.com.br/v1/projects/me/meta-credentials \
  -H "Authorization: Bearer rly_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "metaPhoneNumberId": "SEU_PHONE_NUMBER_ID",
    "metaAccessToken": "SEU_ACCESS_TOKEN",
    "callbackUrl": "https://seusite.com.br/relayos-webhook"
  }'

Your endpoint must be publicly reachable over HTTPS. RelayOS will start delivering events to it immediately after the credential update is saved.

Webhook event payload

Every event RelayOS sends has the same JSON structure. The event field tells you which status transition occurred, and message_id lets you correlate the event to the original message.

{
  "event": "message.delivered",
  "message_id": "msg_01hwz3k8j2fxqbv9r4tp6d",
  "to": "+5511999998888",
  "template": "lembrete_consulta",
  "status": "DELIVERED",
  "meta_message_id": "wamid.HBgLNTUxMTk5OTk5ODg4FQIAERgSM...",
  "occurred_at": "2026-05-14T14:22:10Z"
}

Payload fields

string

required

The type of event that occurred. See the event types table below.

string

required

The RelayOS message ID returned when you called POST /v1/messages. Use this to match events to messages in your system.

string

required

The recipient phone number in E.164 format.

string

required

The name of the template used for this message.

string

required

The new status of the message after this event. Mirrors the event field in upper-case noun form: SENT, DELIVERED, READ, or FAILED.

string

required

The opaque message ID assigned by Meta’s WhatsApp Cloud API (wamid.*). Useful for support escalations.

string

required

ISO 8601 UTC timestamp of when the status change occurred.

Event types

Event	Triggered when
`message.sent`	Meta confirmed the message left their servers toward the recipient’s device.
`message.delivered`	The message arrived on the recipient’s device.
`message.read`	The recipient opened the message (requires read receipts to be enabled).
`message.failed`	All delivery attempts failed after exponential backoff retries.

Request headers RelayOS sends

RelayOS includes the following headers on every webhook POST so your server can identify and deduplicate events:

Header	Value	Description
`X-RelayOS-Event`	e.g. `message.delivered`	The event type, matching the `event` field in the payload.
`X-RelayOS-Delivery`	UUID string	A unique identifier for this specific delivery attempt. Use it to deduplicate retries.
`User-Agent`	`RelayOS/1.0`	Identifies the sender as the RelayOS platform.

Handle and acknowledge events

Your endpoint must respond with any 2xx HTTP status code within a reasonable time. RelayOS considers any other response — including 3xx redirects, 4xx errors, 5xx errors, or a timeout — a failed delivery and will retry.

HTTP/1.1 200 OK

Return 200 immediately after receiving the request, then process the payload asynchronously. If your handler does slow database writes or calls external APIs synchronously, it risks timing out and triggering unnecessary retries. RelayOS retries failed deliveries with exponential backoff, so your endpoint may receive the same event more than once — use X-RelayOS-Delivery to deduplicate.

Get Started

Guides

Configure Webhooks for Message Delivery Events

Configure your callback URL

Webhook event payload

Payload fields

Event types

Request headers RelayOS sends

Handle and acknowledge events

​Configure your callback URL

​Webhook event payload

​Payload fields

​Event types

​Request headers RelayOS sends

​Handle and acknowledge events

Configure your callback URL

Webhook event payload

Payload fields

Event types

Request headers RelayOS sends

Handle and acknowledge events