Platform Events Reference

This section is the definitive source for all webhook event types emitted by Sent.

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"
  }
}
{
  "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": "Telnyx",
    "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 or whatsapp
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)

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, or a STOP/START/HELP keyword. 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": "Telnyx",
    "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.channelstringsms
payload.providerstringUnderlying carrier provider (Telnyx, Sinch, or Vibes)
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 only)
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: DRAFT, PENDING, APPROVED, REJECTED
payload.languagestringTemplate language code (e.g. en_US)
payload.categorystringTemplate category: MARKETING, UTILITY, AUTHENTICATION
payload.channelstringChannel: whatsapp
payload.reasonstring | nullRejection reason (non-null only when status is REJECTED)

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 only)
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

Rate Limits

Webhook delivery is subject to rate limits to ensure reliability:

  • Per endpoint: 200 requests per minute
  • Retry backoff: Exponential backoff on failures
  • Max payload size: 10MB per event

Rate Limit Handling

If your endpoint consistently exceeds rate limits, webhook delivery may be temporarily suspended. Ensure your endpoint can handle the expected event volume.

Setup

How to setup and configure webhooks in Sent

Security

Verify webhook authenticity and implement security best practices for Sent webhooks

On this page

Platform Events Reference
Event Structure
Event Types & Details
message
templates
Event Filtering
Rate Limits