Webhooks
Eventos
Como os eventos chegam ao seu webhook, o envelope e o catálogo de tipos.
Como chega
Seção intitulada “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 |
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
Seção intitulada “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). |
data |
object |
o conteúdo do evento, no formato de format. |
Os dois formatos
Seção intitulada “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 é ovaluedo change reduzido a este fato: o arraymessages(oustatuses, oumessage_echoes) com um elemento só, e ometadatae ocontactscorrespondentes intactos. No Instagram e no Messenger é o item demessaging[].
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:
{ "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" } }}{ "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 traz o schema completo de cada data.
Catálogo
Seção intitulada “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 | |
call.sdp_answer |
o contato atendeu uma ligação sua (com o sdp da resposta) |
sim | |
call.status |
a ligação mudou de estado (RINGING, ACCEPTED, REJECTED) |
sim | |
call.ended |
a ligação terminou, com end_reason e a duração em duration_s |
sim | |
call.permission_updated |
mudou a permissão de chamada do contato (status, expires_at) |
sim | |
group.created · group.create_failed |
a Meta criou (ou não) um grupo | null |
|
group.settings_updated · group.participants_updated · group.join_requested |
mudaram os dados ou os participantes do grupo, ou chegou um pedido de entrada | null |
|
group.suspended · group.unsuspended · group.deleted |
o grupo foi suspenso, liberado ou apagado | null |
|
flow.response |
o contato terminou um Flow (com response e flow_token) |
sim | |
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 |
|
order.received · order.updated |
chegou um carrinho ou mudou um pedido (cobrança, status, pagamento) | sim | |
payment.updated |
a Meta avisou o pagamento de um pedido | sim | |
template.status |
a Meta aprovou, recusou ou pausou um template | null |
|
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 |
|
history.batch |
lote do histórico de 6 meses importado na coexistência | null |
|
contacts.sync |
contatos sincronizados do app na coexistência | null |
|
comment.received |
chegou um comentário (ou resposta a comentário) num post ou live da conta | null |
|
comment.replied |
você respondeu um comentário em público | null |
|
comment.private_replied |
você mandou uma resposta privada a um comentário (vem com a mensagem e o contato) | null |
|
comment.hidden · comment.unhidden |
você ocultou ou voltou a mostrar um comentário | null |
|
comment.deleted |
você apagou um comentário | null |
|
mention.received |
a conta foi mencionada num comentário, legenda ou story (source) |
null |
|
publication.published |
uma publicação saiu, com external_media_id e permalink |
null |
|
publication.failed |
uma publicação falhou, com o motivo em publication.error |
null |
|
campaign.scheduled · campaign.started · campaign.completed · campaign.canceled |
uma campanha foi agendada, começou, terminou ou foi cancelada (data.campaign com status e números) |
null |
|
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 |
|
campaign.progress |
os números da campanha mudaram (no máximo 1 por minuto) | null |
|
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.
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.
Organização
Seção intitulada “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.
{ "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 asequence. - Uma entrega
heldcom mais de 15 dias virafailedcom o erroorg_suspended.
Eventos de WABA e de organização
Seção intitulada “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_alerteflow.endpoint_error;flow.responsenã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.*, comoorg.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
Seção intitulada “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
Seção intitulada “Ordem e duplicatas”- A entrega é pelo menos uma vez: o mesmo evento pode chegar mais de uma vez. Deduplique pelo
Messajo-Event-Id(igual aoiddo envelope). - Eventos podem chegar fora de ordem, inclusive entre entregas e reenvios. Dentro de uma conversa, use
sequencepara ordenar: ela só cresce. - Responda
2xxrá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
Seção intitulada “Tentativas e falhas”- Sucesso = resposta
2xxem 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
Seção intitulada “Lista de falhas e reenvio”- Esgotadas as tentativas, a entrega fica
failede entra na lista de falhas do destino, no painel. - Reenviar cria uma entrega nova do mesmo evento (mesmo
Messajo-Event-Id, novoMessajo-Delivery-Id, tentativa1). Só funciona com o destino ativo. - Para reenviar várias de uma vez, use Reenviar falhas no painel ou
POST /v1/destinations/{id}/redeliver-failedcomsince(euntil, opcional). Cada chamada põe na fila até 1000 falhas e devolve{ queued, has_more }: comhas_more: true, chame de novo. - Entregas e eventos ficam guardados por 30 dias.
Pausa automática
Seção intitulada “Pausa automática”- Um destino é pausado sozinho (
auto_paused) quando junta 10 falhas seguidas e está falhando há pelo menos 24 horas. Qualquer2xxzera a contagem. - Ao pausar, as entregas ainda em andamento desse destino viram
failedcom o errodestination_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
failedcomdestination_paused. Nada se perde: depois de corrigir o endpoint e retomar o destino, reenvie as falhas do período.
Filtros
Seção intitulada “Filtros”Cada destino recebe só o que você escolher:
- por evento: uma lista de padrões. Vale
*(tudo),<família>.*(por exemplomessage.*ouconnection.*) e o tipo exato (por exemplomessage.status). Padrão que não é tipo conhecido nem família conhecida ou reservada é recusado comvalidation_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;
- formato:
normalizedoumeta.
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
Seção intitulada “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.