Skip to main content
Webhooks entregam eventos em tempo real para a sua URL como requisições POST em JSON. Você configura webhooks por número na página Webhooks no painel ou via POST /v1/webhooks — consulte o guia Receber Mensagens para a configuração e a referência de Eventos para os schemas completos de payload.
A página Webhooks no painel do Pilot Status

A página Webhooks — crie endpoints, escolha eventos (ou assine todos com *) e inspecione os logs de entrega.

​
Visão geral dos eventos

Um webhook só dispara para eventos na sua lista events. Uma lista vazia não dispara nada; use "*" para assinar todos os eventos. Os eventos de saúde do número e number.recovered são entregues somente a webhooks assinados com o curinga "*".

​
Schema do payload (v3)

Todo evento message.* / number.* chega como:
Todos os campos de data são camelCase. Números de telefone estão sempre em E.164 com + (sem sufixo de dispositivo, sem @s.whatsapp.net/@lid). Timestamps estão em ISO 8601 em um único campo createdAt. Eventos call.* normalizados são planos (sem o wrapper data).
Mudança incompatível — data.numberId é sempre o ID do número. Em todo evento number.*, data.numberId agora é o ID do número de WhatsApp. Antes, number.created, number.connected e number.removed carregavam o ID interno da instância, enquanto os eventos de saúde já carregavam o ID do número. Se o seu consumidor casava os eventos de ciclo de vida pelo ID da instância, ele vai parar de casar — passe a usar o ID do número. É o mesmo id que o GET /v1/numbers devolve.

​
Correlação com a resposta 202

POST /v1/messages/send responde HTTP 202 com id e correlationId. Use-os para vincular os webhooks ao seu envio: Em message.reply, quotedMessageId é igual ao messageId do seu message.sent original, e contentReplied carrega o texto citado.
O evento message.read (e o status Read nos logs) só ocorre quando o destinatário tem os recibos de leitura do WhatsApp ativados. Caso contrário, o ciclo de vida para em message.delivered.

​
Notas sobre a entrega

  • number.disconnected é emitido a partir da transição de saúde do número, que controla a janela anti-oscilação e a deduplicação de um alerta por transição — um evento por queda confirmada, não um por oscilação do socket. Ele dispara para números web nativos (não oficiais), que antes não produziam nenhum evento assinável quando caíam. Números da Meta Cloud API nunca o emitem: eles sinalizam problemas pelos eventos de saúde, exclusivos do curinga "*".
  • Com a retenção de dados desativada (modos de PII), campos condicionais como content podem estar vazios; IDs e timestamps sempre existem.
  • Eventos que o provedor do número não consegue emitir são silenciosamente descartados de uma assinatura.

​
Relacionados