# Events

> How events reach your webhook, the envelope and the catalog of types.

## How it arrives

Each event arrives as a `POST` with a JSON body to the URL you registered as a destination. The headers of every delivery:

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `Messajo-Webhooks/1` |
| `Messajo-Signature` | `t=<unix s>,v1=<hex>` — see [Verify the signature](/en/webhooks/verify-signature/) |
| `Messajo-Event-Id` | event id (`evt_…`), the same across all attempts and redeliveries |
| `Messajo-Event-Type` | event type, for example `message.received` |
| `Messajo-Delivery-Id` | id of this delivery to this destination (`dlv_…`). A redelivery creates a new delivery, with a new id |
| `Messajo-Delivery-Attempt` | attempt number of this delivery, starting at `1` |

The custom headers you set on the destination are sent too. They never override the `Messajo-*` ones, and `Host`, `Content-Type`, `Content-Length`, `User-Agent`, `Transfer-Encoding` and `Connection` cannot be set.

## Envelope

Every event comes in the same envelope:

| Field | Type | What it is |
|---|---|---|
| `id` | `string` | event id (`evt_…`). Use it to drop duplicates. |
| `type` | `string` | event type, for example `message.received`. |
| `format` | `"normalized"` \| `"meta"` | format **used** in `data` (see below). |
| `org` | `string` | organization id. |
| `connection` | `string` \| `null` | connection id (`conn_…`); `null` on organization events such as `destination.test`. |
| `channel` | `"whatsapp"` \| `"instagram"` \| `"messenger"` \| `null` | the connection's channel; `null` when `connection` is `null`. |
| `timestamp` | `string` | date and time of the fact, ISO 8601 in UTC. |
| `sequence` | `number` \| `null` | increasing per conversation; `null` on events outside a conversation (see the [catalog](#catalog)). |
| `data` | `object` | the event content, in the format given by `format`. |

### The two formats

Each destination picks a format:

- **`normalized`**: Messajo's format, the same across channels, in snake_case.
- **`meta`**: the piece of the Meta webhook that produced the event. On WhatsApp it is the change's `value` reduced to this fact: the `messages` array (or `statuses`, or `message_echoes`) with a single element, and the matching `metadata` and `contacts` untouched. On Instagram and Messenger it is the `messaging[]` item.

An event that does not come from a Meta webhook (for example `message.sent` and `destination.test`) has no `meta` version: it goes out as `normalized` even to a `meta` destination. That is why `format` tells the format that was **used**, not the one the destination asked for. Check `format` before reading `data`.

The same `message.received` in both formats:

```json title="format: normalized"
{
  "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB",
  "type": "message.received",
  "format": "normalized",
  "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y",
  "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T14:03:27.000Z",
  "sequence": 42,
  "data": {
    "contact": {
      "display_name": "Maria",
      "id": "ctc_01JC9W3X5R1P0N9M8L7K6J5H4G",
      "identities": [{ "kind": "wa_id", "scope": "", "value": "5511999999999" }]
    },
    "conversation": {
      "extended_window_ends_at": null,
      "id": "cnv_01JC9W3X5S2Q1P0N9M8L7K6J5H",
      "window_ends_at": "2026-11-10T14:03:27.000Z"
    },
    "message": {
      "content": { "body": "Hi! Has my order shipped?", "type": "text" },
      "context": null,
      "direction": "inbound",
      "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA",
      "id": "msg_01JC9W3X6T3R2Q1P0N9M8L7K6J",
      "source": "customer",
      "timestamp": "2026-11-09T14:03:27.000Z"
    }
  }
}
```

```json title="format: meta"
{
  "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB",
  "type": "message.received",
  "format": "meta",
  "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y",
  "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T14:03:27.000Z",
  "sequence": 42,
  "data": {
    "contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }],
    "messages": [
      {
        "from": "5511999999999",
        "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA",
        "text": { "body": "Hi! Has my order shipped?" },
        "timestamp": "1762697007",
        "type": "text"
      }
    ],
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "106540352242922" }
  }
}
```

The keys of `data` come in alphabetical order and the same event always produces the same bytes, on every attempt. Even so, verify the signature over the raw body, never over re-serialized JSON. The [API reference](/en/reference) has the full schema of each `data`.

## Catalog

| Type | When | `sequence` | Channels |
|---|---|---|---|
| `message.received` | a message from the contact arrived | yes | all |
| `message.sent` | one of your messages was accepted by Meta | yes | all |
| `message.status` | the status of one of your messages changed (delivered, read, failed) | yes | all |
| `message.echo` | message sent outside the API (phone app, Meta Inbox) | yes | all |
| `message.edited` | the contact edited a message | yes | all |
| `message.revoked` | the contact deleted a message | yes | all |
| `call.incoming` | the contact is calling the number (with the offer `sdp`) | yes | WhatsApp |
| `call.sdp_answer` | the contact picked up one of your [calls](/en/guides/calls/) (with the answer `sdp`) | yes | WhatsApp |
| `call.status` | the call changed state (`RINGING`, `ACCEPTED`, `REJECTED`) | yes | WhatsApp |
| `call.ended` | the call ended, with `end_reason` and the duration in `duration_s` | yes | WhatsApp |
| `call.permission_updated` | the contact's call permission changed (`status`, `expires_at`) | yes | WhatsApp |
| `group.created` · `group.create_failed` | Meta created (or did not create) a [group](/en/guides/groups/) | `null` | WhatsApp |
| `group.settings_updated` · `group.participants_updated` · `group.join_requested` | the group's data or participants changed, or a join request arrived | `null` | WhatsApp |
| `group.suspended` · `group.unsuspended` · `group.deleted` | the group was suspended, released or deleted | `null` | WhatsApp |
| `flow.response` | the contact finished a [Flow](/en/guides/flows/) (with `response` and `flow_token`) | yes | WhatsApp |
| `flow.status_changed` · `flow.endpoint_alert` · `flow.endpoint_error` | the Flow status changed, Meta raised an endpoint health alert, or the contact's app reported an error | `null` | WhatsApp |
| `order.received` · `order.updated` | a cart arrived or an [order](/en/guides/commerce/) changed (charge, status, payment) | yes | WhatsApp |
| `payment.updated` | Meta reported an order payment | yes | WhatsApp |
| `template.status` | Meta approved, rejected or paused a template | `null` | WhatsApp |
| `connection.created` | new active connection | `null` | all |
| `connection.updated` | the status changed (to active, restricted or disabled), or the connection's health or data changed; the reason comes in `reason` | `null` | all |
| `connection.disconnected` | the connection was turned off | `null` | all |
| `connection.needs_reconnect` | access dropped and the connection must be redone | `null` | all |
| `connection.error` | Meta reported an account or number error, outside a message (`errors[]`) | `null` | WhatsApp |
| `history.batch` | batch of the 6-month history imported under coexistence | `null` | WhatsApp |
| `contacts.sync` | contacts synced from the app under coexistence | `null` | WhatsApp |
| `comment.received` | a comment (or a reply to a comment) arrived on a post or live of the account | `null` | Instagram |
| `comment.replied` | you replied to a comment in public | `null` | Instagram |
| `comment.private_replied` | you sent a private reply to a comment (comes with the message and the contact) | `null` | Instagram |
| `comment.hidden` · `comment.unhidden` | you hid a comment or showed it again | `null` | Instagram |
| `comment.deleted` | you deleted a comment | `null` | Instagram |
| `mention.received` | the account was mentioned in a comment, caption or story (`source`) | `null` | Instagram |
| `publication.published` | a [publication](/en/connect/instagram-content/#publish) went out, with `external_media_id` and `permalink` | `null` | Instagram |
| `publication.failed` | a publication failed, with the reason in `publication.error` | `null` | Instagram |
| `campaign.scheduled` · `campaign.started` · `campaign.completed` · `campaign.canceled` | a [campaign](/en/guides/campaigns/) was scheduled, started, finished or was canceled (`data.campaign` with status and numbers) | `null` | WhatsApp |
| `campaign.paused` · `campaign.resumed` | the campaign paused or resumed; `reason` gives the reason and `auto: true` when Messajo did it (including `limit_reached`, the 24-hour tier, and `org_suspended`, when the organization is suspended) | `null` | WhatsApp |
| `campaign.progress` | the campaign's numbers changed (at most 1 per minute) | `null` | WhatsApp |
| `org.standing_changed` | the organization's standing changed (`active`, `restricted` or `suspended`), since `1.1.0` | `null` | — |
| `destination.test` | you clicked **Test** on the destination (or called `POST /v1/destinations/{id}/test`) | `null` | — |

Accepting, rejecting, ending and placing calls through the API: see [WhatsApp calls](/en/guides/calls/).

`message.sent` and `message.status` carry `campaign: { id, recipient_id }` when the message came from a campaign, and `null` otherwise. `message.*` events carry `group: { id, external_id, subject }` on a group message (and `null` outside one) and the conversation type in `conversation.kind`.

`message.status` carries `cost: { estimate, currency, rate_card_version }` on the status that triggered a Meta charge and `null` on the others; see [Meta costs](/en/guides/costs/).

### Organization

`org.standing_changed` tells you when the organization's standing changes. `reason` is `payment`, `abuse`, `manual` or `meta_request`, and is `null` when the organization goes back to `active`.

```json
{
  "type": "org.standing_changed",
  "data": {
    "organization": {
      "id": "org_1",
      "standing": "suspended",
      "previous_standing": "restricted",
      "reason": "payment",
      "since": "2026-11-13T12:00:00.000Z"
    }
  }
}
```

- It is emitted **before** the organization's webhooks are held and is never held itself: you always get the suspension notice.
- While the organization is suspended, deliveries get the `held` status. When it comes back, they go out in the order the events were created (queue order); within a conversation, `sequence` applies.
- A `held` delivery older than **15 days** becomes `failed` with the `org_suspended` error.

### WABA and organization events

Two groups of events do not belong to a single connection:

- **WABA events** (`template.*`, `flow.status_changed`, `flow.endpoint_alert` and `flow.endpoint_error`; not `flow.response`, which belongs to the receiving number): Meta emits them for the WhatsApp Business account (WABA), which can hold several numbers. Messajo delivers the event to a destination of **any connection on the same WABA**, once per destination. The global destination receives it too, without duplicates.
- **Organization events** (`org.*`, such as `org.standing_changed`): they have no connection, so they only reach **global destinations** whose filter includes them (`org.*` or `*`). A connection destination never receives them.

### Connection reasons

The `connection.*` events carry the connection in `data.connection`, with `status`, `previous_status` and the reason in `reason`:

| `reason` | Status after | What happened |
|---|---|---|
| `reconnected` | active | The connection was redone (in the panel, by link, or because Meta reconnected the account) |
| `reinstated` | active | Meta reinstated the account after a violation or ban |
| `restriction_lifted` | active | Meta's restriction ended |
| `account_restriction` | restricted | Meta restricted the account for a period |
| `policy_blocked` | restricted | Meta blocked a send due to policy (`368` or `131031`) |
| `violation:<type>` | disabled | Meta flagged a policy violation |
| `banned` | disabled | Meta banned the account |
| `token_invalid` · `meta_token_invalid` | needs reconnect | Meta invalidated the token (error `190`), in a health read or a send |
| `partner_removed` · `partner_removed:<reason>` | disconnected | The account removed Messajo as a partner |
| `app_uninstalled` | disconnected | The app was uninstalled from the account |
| `account_deleted` | disconnected | The account or number was deleted at Meta |
| `offboarded` | disconnected | The account left Meta's platform |
| `user_requested` | disconnected | Someone in the organization disconnected it in the panel or through the API |
| `billing_suspended` | disconnected | The organization was suspended for non-payment and its connections were disconnected |
| `token_expired` | needs reconnect | Legacy: no longer emitted (error 190 now becomes `token_invalid`) |
| `app_deauthorized` | disconnected (Instagram) · needs reconnect (Messenger) | The person who authorized removed the app in Meta's settings |
| `data_deleted` | disconnected | The person asked Meta to delete their data and Messajo deleted the Instagram account data |
| `scheduled_for_disable` | unchanged | Meta scheduled the account to be disabled |
| `quality_changed` | unchanged | The number's quality changed |
| `limit_changed` | unchanged | The messaging tier or the account capacity changed |
| `send_rate_changed` | unchanged | The speed changed (20, 80 or 1,000 msg/s) |
| `can_send_changed` | unchanged | **Sending** changed (available, limited or blocked) |
| `name_approved` · `name_rejected` | unchanged | Meta decided the display name change request |
| `alert` | unchanged | Meta sent an account alert |
| `dm_access_disabled` | unchanged | The Instagram account turned off access to messages outside the app (detected at connect or by the health check) |
| `resubscribed` | unchanged | The app had left the webhook subscription of the account or Page and Messajo subscribed again |
| `policy_enforcement` | restricted or active | Meta blocked or released the Page on Messenger due to policy |

When the status does not change, `previous_status` equals `status`. A status change also emails owners and admins (at most one per reason every 6 h).

## Order and duplicates

- Delivery is **at least once**: the same event may arrive more than once. Deduplicate by `Messajo-Event-Id` (equal to the envelope `id`).
- Events may arrive out of order, including across deliveries and redeliveries. Within a conversation, use `sequence` to order them: it only grows.
- Respond `2xx` fast and process later (in a queue of your own). Heavy work inside the request makes the delivery time out and come back as a retry.

## Retries and failures

- **Success** = a `2xx` response within **10 seconds**, in total. Anything else counts as a failure: another status, timeout, network error or blocked address. Redirects (`3xx`) are **not** followed and count as failures.
- Messajo keeps the first 1024 bytes of the response of each attempt, for you to see in the panel.
- After a failure, it retries following the table below: 1 immediate attempt plus 14 more, over a little more than 23 hours. Each wait varies by ±10% and no attempt goes out later than 24 hours after the delivery was created.

| Attempt | Wait since the previous one | Since the 1st (approx.) |
|---|---|---|
| 1 | — | 0 |
| 2 | 10 s | 10 s |
| 3 | 30 s | 40 s |
| 4 | 1 min | 1 min 40 s |
| 5 | 2 min | 3 min 40 s |
| 6 | 5 min | 8 min 40 s |
| 7 | 10 min | 18 min 40 s |
| 8 | 20 min | 38 min 40 s |
| 9 | 40 min | 1 h 18 min |
| 10 | 1 h | 2 h 18 min |
| 11 | 2 h | 4 h 18 min |
| 12 | 3 h | 7 h 18 min |
| 13 | 4 h | 11 h 18 min |
| 14 | 6 h | 17 h 18 min |
| 15 | 6 h | 23 h 18 min |

### Failure list and redelivery

- Once the attempts run out, the delivery becomes `failed` and goes to the destination's **failure list** in the panel.
- **Redeliver** creates a new delivery of the same event (same `Messajo-Event-Id`, new `Messajo-Delivery-Id`, attempt `1`). It only works while the destination is active.
- To redeliver many at once, use **Redeliver failures** in the panel or `POST /v1/destinations/{id}/redeliver-failed` with `since` (and `until`, optional). Each call queues up to 1000 failures and returns `{ queued, has_more }`: with `has_more: true`, call again.
- Deliveries and events are kept for **30 days**.

### Automatic pause

- A destination is paused automatically (`auto_paused`) when it piles up **10 failures in a row** and has been failing for **at least 24 hours**. Any `2xx` resets the count.
- On pause, the destination's deliveries still in progress become `failed` with the `destination_paused` error, and the organization's owners and admins get an **email**.
- While the destination is paused (automatically or by you), each new event creates a `failed` delivery with `destination_paused`. Nothing is lost: after fixing the endpoint and **resuming** the destination, redeliver the failures of that period.

## Filters

Each destination receives only what you choose:

- **by event**: a list of patterns. Accepted: `*` (everything), `<family>.*` (for example `message.*` or `connection.*`) and the exact type (for example `message.status`). A pattern that is not a known type nor a known or reserved family is rejected with `validation_failed`;
- **by connection**: a connection destination receives only that connection's events; a global destination (no connection) receives events from all of them. See [Destination types](/en/webhooks/destinations/#global-or-per-connection);
- **format**: `normalized` or `meta`.

The event is delivered when some pattern matches the type **and** the destination accepts the event's connection. `destination.test` skips the filters: it goes only to the tested destination, in a single attempt, even when the destination is paused.

## Other destinations

The webhook is the default destination. RabbitMQ, SQS, Kafka and WebSocket receive the same envelope, with the same signature, the same filters and the same retries: see [Destination types](/en/webhooks/destinations/).
