Event catalogue
Every event type WhaBuzz delivers, the envelope that wraps it, and a page per message type with the real payload.
Your endpoints receive events. Each is a JSON object in a common envelope. For Meta-originated events the data field holds Meta's own object verbatim and raw holds the complete Meta POST. The pages in this section show, for each message type, the real Meta payload (from WhaBuzz's test fixtures) and the envelope your endpoint receives for it.
#Event types
| Type | Origin | Meaning |
|---|---|---|
message.inbound | Meta | A customer sent a message. Every Meta message type, including unsupported, reaction, order, system. |
message.status | Meta | sent, delivered, read or failed for a message you sent. |
message.error | Meta | An error Meta reports with no message attached. |
message.echo | Meta | A message sent from the WhatsApp Business app on a coexistence number. |
user.preferences | Meta | A customer changed marketing preferences. Forwarded only; WhaBuzz keeps no registry. |
template.status | Meta | Template review decision or status change. |
template.quality | Meta | Template quality rating changed. |
template.category | Meta | Meta re-categorised a template. |
number.quality | Meta | Number quality rating or messaging tier changed. |
number.name | Meta | Display-name review decision. |
account.update | Meta | WABA-level notices: restrictions, violations, verification, partner changes. |
account.alerts | Meta | Account alerts. |
account.capability | Meta | Business capability or limit changes. |
account.security | Meta | Security notices. |
meta.other | Meta | Any field WhaBuzz has no type for. Never dropped. |
message.outbound | WhaBuzz | Every send you make, single or batch, with Meta's response. |
batch.completed | WhaBuzz | A batch finished or was cancelled. |
number.connection | WhaBuzz | A number's connection state changed. |
token.expiring, token.invalid | WhaBuzz | Daily business-token health check. |
Pages with real payloads are listed in the left navigation. message.echo, user.preferences, account.alerts, account.capability and account.security carry Meta's change value unchanged; WhaBuzz has no captured sample for them yet, so they have no example here. See WhaBuzz events for the ones WhaBuzz raises itself. Subscribe to * to receive all of them, including types added later.
#The envelope
API version 2026-10-16.
{
"id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
"type": "message.inbound",
"api_version": "2026-10-16",
"created_at": "2026-10-16T05:12:03.481Z",
"tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
"waba_id": "26059971920328384",
"phone_number_id": "1013622581841046",
"display_phone_number": "14692311132",
"wamid": "wamid.HBgLMTY1MDU1NTEyMzQ…",
"wa_id": "16505551234",
"user_id": null,
"dedupe_key": "msg:wamid.HBgLMTY1MDU1NTEyMzQ…",
"data": { "messaging_product": "whatsapp", "metadata": { }, "contacts": [ ], "message": { } },
"raw": { "object": "whatsapp_business_account", "entry": [ ] },
"raw_path": "entry[0].changes[0].value.messages[0]"
}| Field | Notes |
|---|---|
id | evt_ plus a ULID. Also in the X-WhaBuzz-Event-Id header. |
type | One of the types above. |
api_version | The envelope version. |
created_at | When Meta's POST reached WhaBuzz. |
tenant_id, waba_id, phone_number_id, display_phone_number | Which business and number the event belongs to. |
wamid | The WhatsApp message id, when the event concerns a message. Otherwise null. |
wa_id | The customer's WhatsApp id (phone number). Null when absent. |
user_id | The customer's business-scoped user id (BSUID), when Meta provides one. Null when absent. |
dedupe_key | Identical across redeliveries of the same fact. See Webhooks. |
data | For messages: Meta's change value without messages[], statuses[] and errors[], plus the one item under message, status or error. For other Meta fields: the change value verbatim plus field. |
raw | The complete body Meta POSTed. One Meta POST holding three statuses becomes three events, each carrying the same raw. Null on WhaBuzz-origin events. |
raw_path | Where in raw this event's item sits. |
The convenience fields are copies of values in data. The BSUID field names follow Meta's current documentation and have not yet been re-checked against a live capture.
#Reading the event log
GET /v1/events lists events with filters; GET /v1/events/{event_id} returns one with its payload, inside your retention window.
This page as Markdown: /events.md. All docs in one file: /llms-full.txt.