Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.relayos.com.br/llms.txt

Use this file to discover all available pages before exploring further.

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

​
event
string
required
The type of event that occurred. See the event types table below.
​
message_id
string
required
The RelayOS message ID returned when you called POST /v1/messages. Use this to match events to messages in your system.
​
to
string
required
The recipient phone number in E.164 format.
​
template
string
required
The name of the template used for this message.
​
status
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.
​
meta_message_id
string
required
The opaque message ID assigned by Meta’s WhatsApp Cloud API (wamid.*). Useful for support escalations.
​
occurred_at
string
required
ISO 8601 UTC timestamp of when the status change occurred.

​
Event types

EventTriggered when
message.sentMeta confirmed the message left their servers toward the recipient’s device.
message.deliveredThe message arrived on the recipient’s device.
message.readThe recipient opened the message (requires read receipts to be enabled).
message.failedAll 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:
HeaderValueDescription
X-RelayOS-Evente.g. message.deliveredThe event type, matching the event field in the payload.
X-RelayOS-DeliveryUUID stringA unique identifier for this specific delivery attempt. Use it to deduplicate retries.
User-AgentRelayOS/1.0Identifies 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.