Webhooks Lifecycle
This page describes what happens between the moment an event occurs inside Sent and the moment your endpoint receives (or stops receiving) a webhook delivery. Everything below is observable from your side — through the request itself or the delivery history in the Sent Dashboard.
Delivery Lifecycle
The diagram below shows the full lifecycle of a single webhook delivery — from event generation, through HTTP delivery to your endpoint, including retries and the conditions under which a webhook can be auto-disabled.
The same flow drives both message events and template events; only the envelope contents differ. Filtering by event_types and event_filters is evaluated when the event is generated — webhooks whose subscription doesn't match the event's sub-type don't receive a delivery attempt.
Each retry uses backoff between attempts. After your configured retry_count (1–5, default 3) is exhausted, the delivery is marked FAILED. Ten consecutive failed events auto-disable the webhook — you'll need to re-enable it from the Sent Dashboard.
End-to-end Message Event Flow
The diagram below shows how a single outbound message moves through its sub-types and the points at which it can branch into message.failed. Inbound events are shown separately because they don't share the outbound state machine.
Not every send produces every event. Channels and carriers vary in how many intermediate statuses they report — for example, some SMS carriers skip straight from routed to delivered. Treat the sub-types as a partial order: if you receive message.delivered, you can safely assume the message was queued, routed, and sent.
Events at a Glance
Sent emits two parent event categories — message and templates — and a handful of sub-types under each. The tables below summarise every webhook event, what triggers it, the direction it travels, and where in the lifecycle it can fail.
Message events order
| Message Events | Direction | SMS | RCS | What it means | Where it can go wrong | |
|---|---|---|---|---|---|---|
QUEUED | Outbound | ✅ | ✅ | ✅ | Sent has accepted the request and is queueing it for routing. | Validation errors (bad number, missing template params) reject the request before this event is emitted. |
ROUTED | Outbound | ✅ | ✅ | ✅ | The message has been assigned to a carrier or channel provider. | Routing can fail if there is no available route to the destination country/channel — emits message.failed. |
SENT | Outbound | ✅ | ✅ | ✅ | The carrier or provider has accepted the message for delivery. | Carrier rejects the payload (e.g. content policy, blocked number) — emits message.failed. |
DELIVERED | Outbound | ✅ | ✅ | ✅ | The message reached the recipient's device. | Handset offline, number unreachable, or carrier delivery receipt missing — emits message.failed (or stays at sent until the receipt times out). |
READ | Outbound | ❌ | ✅ | ✅ | The recipient opened the message. Not emitted for SMS. | Recipient never opens the message, has read-receipts disabled, or the channel doesn't support read receipts (SMS). |
FAILED | Outbound | ✅ | ✅ | ✅ | Terminal failure — the message will not be delivered. The payload includes the failure reason. | This is the failure event. Inspect payload.message_status for the cause. |
RECEIVED | Inbound | ✅ | ✅ | ✅ | A contact replied to one of your numbers (or, on RCS, tapped a quick-reply suggestion chip). | Inbound delivery to your endpoint can still fail at HTTP — see the retry/auto-disable lifecycle above. |
Template events order
Template events are emitted under the templates parent type as Meta updates a template's lifecycle. The most common statuses you'll receive:
| Template Events | Direction | What it means | Where it can go wrong |
|---|---|---|---|
PENDING | Outbound | Template has been submitted to Meta for review. | — |
APPROVED | Outbound | Meta approved the template — it is now usable for WhatsApp sends. | — |
REJECTED | Outbound | Meta rejected the template. The reason is in payload.reason. | Fix the template content or category, then re-submit. |
CATEGORY_UPDATED | Outbound | Meta moved the template to a different category (e.g. MARKETING → UTILITY). The change description is in payload.reason. | — |
Meta may also forward other lifecycle values verbatim (for example PAUSED or DISABLED); your handler should be tolerant of statuses outside the list above.
What's Next
- Subscribe to the events your application needs in the Events Reference — full payload schemas and filtering rules.
- Verify incoming requests against the signing secret described in Signature Verification.
- See Handling Retries for guidance on idempotency, response codes, and recovery.