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": "messages",
  "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": "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
  }
}

Field	Description
`field`	The event type: `messages` or `templates`
`timestamp`	ISO 8601 timestamp of event creation
`payload`	Nested 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.

`messages`

Triggered whenever a message's delivery status changes (sent, delivered, read, failed).

{
  "field": "messages",
  "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": "messages",
  "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": "messages",
  "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": "messages",
  "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"
  }
}

Message Event Fields:

Field	Type	Description
`field`	string	Event type: `messages`
`timestamp`	string	ISO 8601 timestamp of the event
`payload.account_id`	string	Your account UUID
`payload.message_id`	string	Message UUID — use this to look up the message in your DB
`payload.message_status`	string	`SENT`, `DELIVERED`, `READ`, `FAILED`
`payload.channel`	string	`sms` or `whatsapp`
`payload.inbound_number`	string	Recipient phone number (E.164 format)
`payload.outbound_number`	string	Sender phone number
`payload.template_id`	string \| null	UUID 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.

Status Definitions:

Status	Description
`SENT`	Message sent to carrier or WhatsApp
`DELIVERED`	Message delivered to recipient's device
`READ`	Message read by recipient (WhatsApp only)
`FAILED`	Message delivery failed permanently

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

Field	Type	Description
`field`	string	Event type: `templates`
`timestamp`	string	ISO 8601 timestamp of the event
`payload.account_id`	string	Your account UUID
`payload.template_id`	string	Template UUID in Sent
`payload.template_name`	string	Template name
`payload.whatsapp_template_id`	string \| null	Meta's WhatsApp template ID (null until approved)
`payload.status`	string	Template status: `DRAFT`, `PENDING`, `APPROVED`, `REJECTED`
`payload.language`	string	Template language code (e.g. `en_US`)
`payload.category`	string	Template category: `MARKETING`, `UTILITY`, `AUTHENTICATION`
`payload.channel`	string	Channel: `whatsapp`
`payload.reason`	string \| null	Rejection 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.

Available Filters:

Messages - Filter message status updates (delivered, failed, etc.)
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.