# Eventos

> Como os eventos chegam ao seu webhook, o envelope e o catálogo de tipos.

## Como chega

Cada evento chega como um `POST` com corpo JSON na URL que você cadastrou como destino. Os cabeçalhos de cada entrega:

| Cabeçalho | Valor |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `Messajo-Webhooks/1` |
| `Messajo-Signature` | `t=<unix s>,v1=<hex>` — veja [Verificar a assinatura](/webhooks/verify-signature/) |
| `Messajo-Event-Id` | id do evento (`evt_…`), o mesmo em todas as tentativas e reenvios |
| `Messajo-Event-Type` | tipo do evento, por exemplo `message.received` |
| `Messajo-Delivery-Id` | id desta entrega para este destino (`dlv_…`). Um reenvio cria uma entrega nova, com id novo |
| `Messajo-Delivery-Attempt` | número da tentativa desta entrega, começando em `1` |

Os cabeçalhos próprios que você cadastrar no destino vão junto. Eles nunca substituem os `Messajo-*`, e `Host`, `Content-Type`, `Content-Length`, `User-Agent`, `Transfer-Encoding` e `Connection` não podem ser cadastrados.

## Envelope

Todo evento vem no mesmo envelope:

| Campo | Tipo | O que é |
|---|---|---|
| `id` | `string` | id do evento (`evt_…`). Use para descartar duplicatas. |
| `type` | `string` | tipo do evento, por exemplo `message.received`. |
| `format` | `"normalized"` \| `"meta"` | formato **usado** em `data` (veja abaixo). |
| `org` | `string` | id da organização. |
| `connection` | `string` \| `null` | id da conexão (`conn_…`); `null` em evento da organização, como `destination.test`. |
| `channel` | `"whatsapp"` \| `"instagram"` \| `"messenger"` \| `null` | canal da conexão; `null` quando `connection` é `null`. |
| `timestamp` | `string` | data e hora do fato, ISO 8601 em UTC. |
| `sequence` | `number` \| `null` | crescente por conversa; `null` em eventos fora de conversa (veja o [catálogo](#catálogo)). |
| `data` | `object` | o conteúdo do evento, no formato de `format`. |

### Os dois formatos

Cada destino escolhe um formato:

- **`normalized`**: formato do Messajo, igual em todos os canais, em snake_case.
- **`meta`**: o pedaço do webhook da Meta que gerou o evento. No WhatsApp é o `value` do *change* reduzido a este fato: o array `messages` (ou `statuses`, ou `message_echoes`) com um elemento só, e o `metadata` e o `contacts` correspondentes intactos. No Instagram e no Messenger é o item de `messaging[]`.

Evento que não nasce de um webhook da Meta (por exemplo `message.sent` e `destination.test`) não tem versão `meta`: sai `normalized` mesmo para destino `meta`. Por isso o campo `format` diz o formato que foi **usado**, não o que o destino pediu. Confira `format` antes de ler `data`.

O mesmo `message.received` nos dois formatos:

```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": "Olá! Meu pedido já saiu?", "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": "Olá! Meu pedido já saiu?" },
        "timestamp": "1762697007",
        "type": "text"
      }
    ],
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "106540352242922" }
  }
}
```

As chaves de `data` saem em ordem alfabética e o mesmo evento gera sempre os mesmos bytes, em todas as tentativas. Mesmo assim, verifique a assinatura sobre o corpo cru, nunca sobre um JSON re-serializado. A [referência da API](/reference) traz o schema completo de cada `data`.

## Catálogo

| Tipo | Quando | `sequence` | Canais |
|---|---|---|---|
| `message.received` | chegou uma mensagem do contato | sim | todos |
| `message.sent` | uma mensagem sua foi aceita pela Meta | sim | todos |
| `message.status` | mudou o status de uma mensagem sua (entregue, lida, falhou) | sim | todos |
| `message.echo` | mensagem enviada por fora da API (app no celular, Inbox da Meta) | sim | todos |
| `message.edited` | o contato editou uma mensagem | sim | todos |
| `message.revoked` | o contato apagou uma mensagem | sim | todos |
| `call.incoming` | o contato está ligando para o número (com o `sdp` da oferta) | sim | WhatsApp |
| `call.sdp_answer` | o contato atendeu uma [ligação](/guides/calls/) sua (com o `sdp` da resposta) | sim | WhatsApp |
| `call.status` | a ligação mudou de estado (`RINGING`, `ACCEPTED`, `REJECTED`) | sim | WhatsApp |
| `call.ended` | a ligação terminou, com `end_reason` e a duração em `duration_s` | sim | WhatsApp |
| `call.permission_updated` | mudou a permissão de chamada do contato (`status`, `expires_at`) | sim | WhatsApp |
| `group.created` · `group.create_failed` | a Meta criou (ou não) um [grupo](/guides/groups/) | `null` | WhatsApp |
| `group.settings_updated` · `group.participants_updated` · `group.join_requested` | mudaram os dados ou os participantes do grupo, ou chegou um pedido de entrada | `null` | WhatsApp |
| `group.suspended` · `group.unsuspended` · `group.deleted` | o grupo foi suspenso, liberado ou apagado | `null` | WhatsApp |
| `flow.response` | o contato terminou um [Flow](/guides/flows/) (com `response` e `flow_token`) | sim | WhatsApp |
| `flow.status_changed` · `flow.endpoint_alert` · `flow.endpoint_error` | mudou o status do Flow, a Meta alertou sobre a saúde do endpoint, ou o app do contato avisou um erro | `null` | WhatsApp |
| `order.received` · `order.updated` | chegou um carrinho ou mudou um [pedido](/guides/commerce/) (cobrança, status, pagamento) | sim | WhatsApp |
| `payment.updated` | a Meta avisou o pagamento de um pedido | sim | WhatsApp |
| `template.status` | a Meta aprovou, recusou ou pausou um template | `null` | WhatsApp |
| `connection.created` | nova conexão ativa | `null` | todos |
| `connection.updated` | mudou o status (para ativa, restrita ou desativada), a saúde ou os dados da conexão; o motivo vem em `reason` | `null` | todos |
| `connection.disconnected` | a conexão foi desligada | `null` | todos |
| `connection.needs_reconnect` | o acesso caiu e a conexão precisa ser refeita | `null` | todos |
| `connection.error` | a Meta avisou um erro da conta ou do número, fora de uma mensagem (`errors[]`) | `null` | WhatsApp |
| `history.batch` | lote do histórico de 6 meses importado na coexistência | `null` | WhatsApp |
| `contacts.sync` | contatos sincronizados do app na coexistência | `null` | WhatsApp |
| `comment.received` | chegou um comentário (ou resposta a comentário) num post ou live da conta | `null` | Instagram |
| `comment.replied` | você respondeu um comentário em público | `null` | Instagram |
| `comment.private_replied` | você mandou uma resposta privada a um comentário (vem com a mensagem e o contato) | `null` | Instagram |
| `comment.hidden` · `comment.unhidden` | você ocultou ou voltou a mostrar um comentário | `null` | Instagram |
| `comment.deleted` | você apagou um comentário | `null` | Instagram |
| `mention.received` | a conta foi mencionada num comentário, legenda ou story (`source`) | `null` | Instagram |
| `publication.published` | uma [publicação](/connect/instagram-content/#publicar) saiu, com `external_media_id` e `permalink` | `null` | Instagram |
| `publication.failed` | uma publicação falhou, com o motivo em `publication.error` | `null` | Instagram |
| `campaign.scheduled` · `campaign.started` · `campaign.completed` · `campaign.canceled` | uma [campanha](/guides/campaigns/) foi agendada, começou, terminou ou foi cancelada (`data.campaign` com status e números) | `null` | WhatsApp |
| `campaign.paused` · `campaign.resumed` | a campanha pausou ou voltou; `reason` diz o motivo e `auto: true` quando foi o Messajo (inclusive `limit_reached`, a faixa de 24 h, e `org_suspended`, quando a organização é suspensa) | `null` | WhatsApp |
| `campaign.progress` | os números da campanha mudaram (no máximo 1 por minuto) | `null` | WhatsApp |
| `org.standing_changed` | a situação da organização mudou (`active`, `restricted` ou `suspended`), desde a `1.1.0` | `null` | — |
| `destination.test` | você clicou em **Testar** no destino (ou chamou `POST /v1/destinations/{id}/test`) | `null` | — |

Atender, recusar, encerrar e fazer ligações pela API: veja [Ligações no WhatsApp](/guides/calls/).

`message.sent` e `message.status` trazem `campaign: { id, recipient_id }` quando a mensagem saiu de uma campanha, e `null` nos outros casos. Os eventos `message.*` trazem `group: { id, external_id, subject }` numa mensagem de grupo (e `null` fora dele) e o tipo da conversa em `conversation.kind`.

`message.status` traz `cost: { estimate, currency, rate_card_version }` no status que gerou cobrança da Meta e `null` nos demais; veja [Custos da Meta](/guides/costs/).

### Organização

`org.standing_changed` avisa quando a situação da organização muda. `reason` é `payment`, `abuse`, `manual` ou `meta_request`, e vem `null` quando a organização volta a `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"
    }
  }
}
```

- É emitido **antes** de os webhooks da organização serem retidos e nunca é retido: você sempre recebe o aviso da suspensão.
- Enquanto a organização está suspensa, as entregas ficam com status `held`. Ao voltar, saem na ordem de criação do evento (ordem de enfileiramento); dentro de uma conversa vale a `sequence`.
- Uma entrega `held` com mais de **15 dias** vira `failed` com o erro `org_suspended`.

### Eventos de WABA e de organização

Dois grupos de eventos não pertencem a uma só conexão:

- **Eventos de WABA** (`template.*`, `flow.status_changed`, `flow.endpoint_alert` e `flow.endpoint_error`; `flow.response` não, é do número que recebeu): a Meta os emite para a conta do WhatsApp Business (WABA), que pode ter vários números. O Messajo entrega o evento a um destino de **qualquer conexão da mesma WABA**, e uma vez por destino. O destino global também recebe e não duplica.
- **Eventos de organização** (`org.*`, como `org.standing_changed`): não têm conexão, então só chegam a **destinos globais** cujo filtro os inclua (`org.*` ou `*`). Um destino de conexão nunca os recebe.

### Motivos da conexão

Os eventos `connection.*` trazem a conexão em `data.connection`, com `status`, `previous_status` e o motivo em `reason`:

| `reason` | Status depois | O que houve |
|---|---|---|
| `reconnected` | ativa | A conexão foi refeita (pelo painel, por link ou porque a Meta reconectou a conta) |
| `reinstated` | ativa | A Meta reativou a conta depois de uma violação ou banimento |
| `restriction_lifted` | ativa | A restrição da Meta acabou |
| `account_restriction` | restrita | A Meta restringiu a conta por um prazo |
| `policy_blocked` | restrita | A Meta bloqueou um envio por política (`368` ou `131031`) |
| `violation:<tipo>` | desativada | A Meta apontou uma violação de política |
| `banned` | desativada | A Meta baniu a conta |
| `token_invalid` · `meta_token_invalid` | precisa reconectar | A Meta invalidou o token (erro `190`), numa leitura de saúde ou num envio |
| `partner_removed` · `partner_removed:<motivo>` | desconectada | A conta tirou o Messajo como parceiro |
| `app_uninstalled` | desconectada | O app foi desinstalado da conta |
| `account_deleted` | desconectada | A conta ou o número foi apagado na Meta |
| `offboarded` | desconectada | A conta saiu da plataforma da Meta |
| `user_requested` | desconectada | Alguém da organização desconectou pelo painel ou pela API |
| `billing_suspended` | desconectada | A organização foi suspensa por falta de pagamento e as conexões foram desconectadas |
| `token_expired` | precisa reconectar | Legado: não é mais emitido (o erro 190 agora vira `token_invalid`) |
| `app_deauthorized` | desconectada (Instagram) · precisa reconectar (Messenger) | A pessoa que autorizou removeu o app nas configurações da Meta |
| `data_deleted` | desconectada | A pessoa pediu a exclusão dos dados à Meta e o Messajo apagou os dados da conta do Instagram |
| `scheduled_for_disable` | sem mudança | A Meta agendou a desativação da conta |
| `quality_changed` | sem mudança | Mudou a qualidade do número |
| `limit_changed` | sem mudança | Mudou a faixa de envio ou a capacidade da conta |
| `send_rate_changed` | sem mudança | Mudou a velocidade (20, 80 ou 1.000 msg/s) |
| `can_send_changed` | sem mudança | Mudou o **Envio** (liberado, limitado ou bloqueado) |
| `name_approved` · `name_rejected` | sem mudança | A Meta decidiu o pedido de troca do nome exibido |
| `alert` | sem mudança | A Meta mandou um alerta da conta |
| `dm_access_disabled` | sem mudança | A conta do Instagram desativou o acesso às mensagens fora do app (detectado ao conectar ou pelo health check) |
| `resubscribed` | sem mudança | O app tinha saído da inscrição de webhooks da conta ou da Página e o Messajo inscreveu de novo |
| `policy_enforcement` | restrita ou ativa | A Meta bloqueou ou liberou a Página no Messenger por política |

Quando o status não muda, `previous_status` é igual a `status`. Mudança de status também manda e-mail para donos e admins (no máximo um por motivo a cada 6 h).

## Ordem e duplicatas

- A entrega é **pelo menos uma vez**: o mesmo evento pode chegar mais de uma vez. Deduplique pelo `Messajo-Event-Id` (igual ao `id` do envelope).
- Eventos podem chegar fora de ordem, inclusive entre entregas e reenvios. Dentro de uma conversa, use `sequence` para ordenar: ela só cresce.
- Responda `2xx` rápido e processe depois (numa fila sua). Trabalho pesado dentro da requisição faz a entrega estourar o tempo e voltar como tentativa.

## Tentativas e falhas

- **Sucesso** = resposta `2xx` em até **10 segundos**, no total. Qualquer outra coisa conta como falha: outro status, tempo esgotado, erro de rede ou endereço bloqueado. Redirecionamento (`3xx`) **não** é seguido e conta como falha.
- O Messajo guarda os primeiros 1024 bytes da resposta de cada tentativa, para você ver no painel.
- Depois de uma falha, tenta de novo segundo a tabela abaixo: 1 tentativa imediata e mais 14, ao longo de pouco mais de 23 horas. Cada espera varia ±10% e nenhuma tentativa sai depois de 24 horas da criação da entrega.

| Tentativa | Espera desde a anterior | Desde a 1ª (aprox.) |
|---|---|---|
| 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 |

### Lista de falhas e reenvio

- Esgotadas as tentativas, a entrega fica `failed` e entra na **lista de falhas** do destino, no painel.
- **Reenviar** cria uma entrega nova do mesmo evento (mesmo `Messajo-Event-Id`, novo `Messajo-Delivery-Id`, tentativa `1`). Só funciona com o destino ativo.
- Para reenviar várias de uma vez, use **Reenviar falhas** no painel ou `POST /v1/destinations/{id}/redeliver-failed` com `since` (e `until`, opcional). Cada chamada põe na fila até 1000 falhas e devolve `{ queued, has_more }`: com `has_more: true`, chame de novo.
- Entregas e eventos ficam guardados por **30 dias**.

### Pausa automática

- Um destino é pausado sozinho (`auto_paused`) quando junta **10 falhas seguidas** e está falhando há **pelo menos 24 horas**. Qualquer `2xx` zera a contagem.
- Ao pausar, as entregas ainda em andamento desse destino viram `failed` com o erro `destination_paused`, e donos e admins da organização recebem um **e-mail**.
- Enquanto o destino estiver pausado (sozinho ou por você), cada evento novo gera uma entrega `failed` com `destination_paused`. Nada se perde: depois de corrigir o endpoint e **retomar** o destino, reenvie as falhas do período.

## Filtros

Cada destino recebe só o que você escolher:

- **por evento**: uma lista de padrões. Vale `*` (tudo), `<família>.*` (por exemplo `message.*` ou `connection.*`) e o tipo exato (por exemplo `message.status`). Padrão que não é tipo conhecido nem família conhecida ou reservada é recusado com `validation_failed`;
- **por conexão**: um destino de conexão recebe só os eventos dela; um destino global (sem conexão) recebe os de todas. Veja [Tipos de destino](/webhooks/destinations/#global-ou-por-conexão);
- **formato**: `normalized` ou `meta`.

O evento chega quando algum padrão casa com o tipo **e** o destino aceita a conexão do evento. O `destination.test` não passa pelos filtros: vai só para o destino testado, numa tentativa única, mesmo com o destino pausado.

## Outros destinos

O webhook é o destino padrão. RabbitMQ, SQS, Kafka e WebSocket recebem o mesmo envelope, com a mesma assinatura, os mesmos filtros e as mesmas tentativas: veja [Tipos de destino](/webhooks/destinations/).
