Pular para o conteúdo

Webhooks

Eventos

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

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.

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.

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:

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"
}
}
}
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 traz o schema completo de cada data.

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 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 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 (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 (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 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 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.

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.

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 a sequence.
  • Uma entrega held com mais de 15 dias vira failed com o erro org_suspended.

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.

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).

  • 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.
  • 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
  • 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.
  • 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.

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;
  • 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.

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.