Platform Events Reference

This section is the definitive source for all webhook event types emitted by Sent. For an end-to-end view of delivery, retries, and the full event catalogue at a glance, see the Webhooks Lifecycle page.

Event Structure

Every event that your webhook endpoint will receive has a consistent envelope:

{
  "field": "message",
  "sub_type": "message.delivered",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "DELIVERED",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "agent_id": "agent_abc123"
  }
}
{
  "field": "message",
  "sub_type": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "from": "+1234567890",
    "to": "+1987654321",
    "text": "Hello, I have a question about my order",
    "channel": "sms",
    "provider": "<provider-name>",
    "received_at": "2025-10-31T10:10:40Z"
  }
}
{
  "field": "templates",
  "timestamp": "2025-10-31T12:18:14Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "whatsapp_template_id": "1234567890123456",
    "status": "APPROVED",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp",
    "reason": null
  }
}
FieldTypeDescription
fieldstringThe parent event type: message or templates
sub_typestring | omittedGranular sub-type (e.g. message.delivered). Present for all message events; omitted for template events
timestampstringISO 8601 timestamp of event creation
payloadobjectNested object containing event-specific data

Event Types & Details

Below you will find the details of the events that you will receive in your webhook endpoint.

Your handler receives the full event object — field, timestamp, and the nested payload. The Sent Dashboard also tracks delivery metadata (HTTP status, attempts, response body) separately from the event payload itself.

message

Triggered whenever a message's delivery status changes, or when an inbound message is received. Each status transition fires a separate event with a matching sub_type.

Outbound message status events:

{
  "field": "message",
  "sub_type": "message.queued",
  "timestamp": "2025-10-31T12:10:05Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "QUEUED",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}
{
  "field": "message",
  "sub_type": "message.routed",
  "timestamp": "2025-10-31T12:10:22Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "ROUTED",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}
{
  "field": "message",
  "sub_type": "message.sent",
  "timestamp": "2025-10-31T12:12:33Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "SENT",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}
{
  "field": "message",
  "sub_type": "message.delivered",
  "timestamp": "2025-10-31T12:15:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "DELIVERED",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}
{
  "field": "message",
  "sub_type": "message.read",
  "timestamp": "2025-10-31T11:45:06Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "READ",
    "channel": "whatsapp",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}
{
  "field": "message",
  "sub_type": "message.failed",
  "timestamp": "2025-10-31T09:52:24Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "message_status": "FAILED",
    "channel": "sms",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"
  }
}

Outbound Message Event Fields (message.queued through message.failed):

FieldTypeDescription
fieldstringParent event type: message
sub_typestringGranular sub-type — one of message.queued, message.routed, message.sent, message.delivered, message.read, message.failed
timestampstringISO 8601 timestamp of the event
payload.account_idstringYour account UUID
payload.message_idstringMessage UUID — use this to look up the message in your DB
payload.message_statusstringQUEUED, ROUTED, SENT, DELIVERED, READ, FAILED
payload.channelstringsms, whatsapp, or rcs
payload.inbound_numberstringRecipient phone number (E.164 format)
payload.outbound_numberstringSender phone number
payload.template_idstring | nullUUID of the template used (null if no template)
payload.agent_idstring | omittedIdentifier of the agent that originated the message (omitted when not set)

Note: The Sent Dashboard shows additional metadata about webhook delivery (attempts, HTTP status, response body) that is not part of the event payload itself.

Inbound message event (message.received):

Fires when an end-user sends a message to one of your provisioned numbers — for example, a reply to an outbound campaign, a STOP/START/HELP keyword on SMS, or a free-text reply on WhatsApp. The payload shape is different from outbound status events:

{
  "field": "message",
  "sub_type": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "from": "+1234567890",
    "to": "+1987654321",
    "text": "Hello, I have a question about my order",
    "channel": "sms",
    "provider": "<provider-name>",
    "received_at": "2025-10-31T10:10:40Z"
  }
}
{
  "field": "message",
  "sub_type": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "from": "+1234567890",
    "to": "+1987654321",
    "text": "Thanks, got your message!",
    "channel": "whatsapp",
    "provider": "<provider-name>",
    "received_at": "2025-10-31T10:10:40Z"
  }
}
{
  "field": "message",
  "sub_type": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "from": "+1234567890",
    "to": "+1987654321",
    "text": "Tapped: View order",
    "channel": "rcs",
    "provider": "<provider-name>",
    "received_at": "2025-10-31T10:10:40Z"
  }
}

Inbound Message Event Fields (message.received):

FieldTypeDescription
fieldstringParent event type: message
sub_typestringAlways message.received
timestampstringISO 8601 timestamp of the event
payload.account_idstringYour account UUID
payload.fromstringSender's phone number (the contact) in E.164 format
payload.tostringYour provisioned number that received the message
payload.textstring | nullMessage body text
payload.channelstringChannel the message arrived on: sms, whatsapp, or rcs
payload.providerstringName of the upstream channel provider that delivered the inbound message. Use it for logging or debugging; specific values may change over time.
payload.received_atstringISO 8601 timestamp when the provider received the message

Status Definitions:

StatusSub-typeDirectionDescription
QUEUEDmessage.queuedOutboundMessage accepted and waiting to be dispatched
ROUTEDmessage.routedOutboundMessage assigned to a carrier or provider
SENTmessage.sentOutboundMessage sent to carrier or WhatsApp
DELIVEREDmessage.deliveredOutboundMessage delivered to recipient's device
READmessage.readOutboundMessage read by recipient (WhatsApp & RCS)
FAILEDmessage.failedOutboundMessage delivery failed permanently
RECEIVEDmessage.receivedInboundInbound message received from a contact

templates

Triggered when a WhatsApp template moves through the approval process.

{
  "field": "templates",
  "timestamp": "2025-10-31T12:18:14Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "whatsapp_template_id": "1234567890123456",
    "status": "APPROVED",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp",
    "reason": null
  }
}

Template Event Fields:

FieldTypeDescription
fieldstringEvent type: templates
timestampstringISO 8601 timestamp of the event
payload.account_idstringYour account UUID
payload.template_idstringTemplate UUID in Sent
payload.template_namestringTemplate name
payload.whatsapp_template_idstringMeta's WhatsApp template ID (empty string until approved)
payload.statusstringTemplate status — typically PENDING, APPROVED, REJECTED, or CATEGORY_UPDATED. Meta may also emit other lifecycle values (e.g. PAUSED, DISABLED) which are forwarded verbatim.
payload.languagestringTemplate language code (e.g. en_US)
payload.categorystringTemplate category: MARKETING, UTILITY, AUTHENTICATION
payload.channelstringChannel: whatsapp
payload.reasonstring | omittedReason supplied by Meta (e.g. rejection reason for REJECTED, change description for CATEGORY_UPDATED). Omitted when not set.

Event Filtering

You can configure which events to receive in the webhook settings in your Sent Dashboard to reduce noise and improve performance.

Subscribe to specific event types when creating or updating a webhook by setting event_types and, optionally, event_filters:

{
  "event_types": ["message", "templates"],
  "event_filters": {
    "message": ["delivered", "failed", "read", "received"]
  }
}

The event_filters map accepts a parent event_type as the key and a list of sub-type suffixes as values. In the example above only message.delivered, message.failed, message.read, and message.received events are delivered — message.queued, message.routed, and message.sent are suppressed.

Available Sub-type Filters for message:

ValueFires forDirection
queuedmessage.queuedOutbound
routedmessage.routedOutbound
sentmessage.sentOutbound
deliveredmessage.deliveredOutbound
readmessage.readOutbound (WhatsApp & RCS)
failedmessage.failedOutbound
receivedmessage.receivedInbound

Available Filters:

  • Message — Subscribe to all or specific message.* sub-types (outbound status + inbound message.received)
  • Templates — Filter by specific template names

Delivery Headers & Signing

Every outgoing webhook request includes the following headers so that you can authenticate and de-duplicate events:

HeaderDescription
X-Webhook-IDUUID of the webhook configuration that produced the request
X-Webhook-TimestampUnix timestamp in seconds at which the request was signed
X-Webhook-Signaturev1,{base64_hmac} — HMAC-SHA256 over {webhook_id}.{timestamp}.{raw_body} using your signing secret
X-Webhook-Event-TypeFully qualified event type (message.delivered, templates, etc.)

Signing secrets are issued in the Sent Dashboard prefixed with whsec_ (Svix-compatible). Always verify the signature server-side before trusting the payload, and compare the timestamp against your clock to reject replayed requests.

Delivery Statuses & Retries

Each webhook delivery is tracked in the Sent Dashboard with its own row and lifecycle:

StatusMeaning
PENDINGEvent created, queued for delivery
RETRYINGA previous attempt failed; the next attempt is scheduled with backoff
DELIVEREDEndpoint returned 2xx; consecutive-failure counter resets to 0
FAILEDExceeded the webhook's configured retry count (retry_count, 1–5, defaults to 3)

Per-event metadata stored alongside each attempt includes the delivery attempt count, HTTP status code, the first portion of the response body, the error message, and start/completion timestamps — all surfaced in the Sent Dashboard's webhook event detail view.

Auto-disable after consecutive failures

If a webhook accumulates 10 consecutive failed deliveries (configurable per environment) it is automatically disabled. This guards against expired or compromised endpoints. Re-enable the webhook from the Sent Dashboard once your endpoint is healthy again.

Delivery Constraints

Webhook configuration is subject to the following constraints:

  • Per-webhook timeout: 5–120 seconds, defaults to 30 seconds (configured when you create or update the webhook)
  • Retry count: 1–5 attempts per event, defaults to 3
  • URL scheme: must be http:// or https://
  • URL validation: private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.) are rejected at creation, update, and delivery time

Lifecycle

End-to-end webhook delivery lifecycle and the full set of events Sent can emit

Security

Verify webhook authenticity and implement security best practices for Sent webhooks

On this page

Platform Events ReferenceEvent StructureEvent Types & DetailsmessagetemplatesEvent FilteringDelivery Headers & SigningDelivery Statuses & RetriesDelivery Constraints