Standard event types & payload
The unified envelope every delivery carries and the full catalogue of standard event types. Subscribe per endpoint with subscribed_events using the exact names below, or use ["*"] for all. The envelope is always id / type / provider / account_id / occurred_at / data; the shape of data depends on type.
Event payload
{
"id": "evt_2f9c1a4b7e",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:34:56Z",
"data": {
"account": { "provider_account_ref": "8613800138000" },
"conversation": { "id": "8613912345678", "type": "user", "title": "Jordan Lee" },
"sender": { "id": "8613912345678", "name": "Jordan Lee", "type": "user" },
"message": {
"id": "wamid.HBgM",
"text": "Hi - is my order shipped yet?",
"direction": "inbound",
"sent_at": "2026-06-08T12:34:55Z"
}
}
}Standard event types
- message.received
An inbound message arrived on the account.
- message.updated
A previously delivered message was edited.
- message.deleted
A message was deleted or recalled.
- message.read
A read receipt — the recipient read a message.
- message.reaction
A reaction was added to or removed from a message.
- message.delivered
A message was delivered to the recipient's device.
- conversation.updated
A conversation-level setting changed — muted/unmuted, archived, pinned, or marked read.
- conversation.deleted
A conversation was deleted.
- conversation.cleared
A conversation's history was cleared.
- conversation.history
Recent WhatsApp history for one conversation was synced after bootstrap or reconnect.
- group.updated
Group metadata changed — name, members, or settings.
- group.join_request
Someone asked to join a group with join approval enabled. Push is best-effort — poll List group join requests as the reliable source.
- account.status.updated
The account runtime / connection status changed.
- account.started
The account runtime connected and is ready to send and receive.
- account.history.synced
A WhatsApp history-sync batch finished; data.summary gives the delivered conversation and message counts.
- account.auth.required
The account needs (re)authentication — a code, QR scan, or 2FA.
- account.auth.succeeded
Authentication finished and the account is online.
- account.auth.failed
An authentication attempt failed.
Примечания
- For media messages, data.message.attachments[] carries a temporary signed OSS url plus type, mimetype, and size.
- subscribed_events must contain exact event names from above or ["*"]. Unknown names are rejected when you create or update the endpoint.
- Not every provider emits every event, and some payload fields differ — see "Webhook standard event differences" for the per-provider matrix.
- message.read and message.delivered carry the exact receipt scope: data.message.ids lists every message covered by the receipt, and read_at / delivered_at give the provider-reported time.
- WhatsApp inbound messages include data.message.reply_token — an opaque handle you pass back in reply_to.reply_token of POST /v1/messages to send a quoted reply. Store it alongside the message if you plan to reply later.