# Event catalogue

> Every event type WhaBuzz delivers, the envelope that wraps it, and a page per message type with the real payload.

Canonical: https://docs.whabuzz.com/events/

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 {#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](https://docs.whabuzz.com/events/whabuzz-events.md) for the ones WhaBuzz raises itself. Subscribe to `*` to receive all of them, including types added later.

## The envelope {#envelope}

API version `2026-10-16`.

```json
{
  "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](https://docs.whabuzz.com/guides/webhooks.md#dedupe). |
| `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 {#log}

[`GET /v1/events`](https://docs.whabuzz.com/api/events.md#listEvents) lists events with filters; [`GET /v1/events/{event_id}`](https://docs.whabuzz.com/api/events.md#getEvent) returns one with its payload, inside your [retention](https://docs.whabuzz.com/guides/retention.md) window.