Webhook do WhatsApp API: como as respostas e os status chegam ao seu sistema

O que é o webhook da API do WhatsApp e para que serve?

Webhooks são requisições HTTP com conteúdo em JSON que os servidores da Meta enviam para um endereço que você define. Na API do WhatsApp, o campo messages cobre dois tipos de aviso: as mensagens que os clientes mandam para a empresa e as atualizações de status das mensagens que a empresa enviou. Em vez de perguntar à Meta o tempo todo se algo mudou, o seu sistema é avisado quando acontece.

Para o disparo em massa, isso resolve duas coisas. A primeira é o atendimento: a resposta do cliente chega ao CRM e cai na fila de quem vai atender. A segunda é a medição: cada mensagem recebe um status, e a soma dos status vira o relatório da campanha. Se você quer entender o conceito de webhook em geral, veja o que é webhook; aqui o foco é o WhatsApp.

O que a Meta envia pelo webhook?

No caminho de saída, cada mensagem enviada gera avisos de status. Segundo a documentação da Meta, os valores são estes:

Cada aviso traz o identificador da mensagem, o status, o horário, o número do destinatário e, quando há falha, um bloco de erro com código e descrição. Um dos avisos (sent, delivered ou read) também traz o bloco de cobrança, com a categoria da mensagem. Um detalhe útil para campanhas: se você enviar um valor próprio de controle junto com a mensagem (o campo de dados opacos de retorno), ele volta no status. Dá para carregar ali o código da campanha e cruzar o resultado com a sua planilha depois.

O seu sistema precisa aceitar que o entregue não chegue: quando a mensagem é lida no instante em que chega, a Meta manda só o lido. Também precisa aceitar avisos repetidos, por causa das novas tentativas descritas adiante. Para entender o que cada código de falha quer dizer, use códigos de erro da API do WhatsApp e status de entrega da API do WhatsApp.

O webhook também carrega avisos da conta, além das mensagens: a Meta notifica pausa de template (por webhook, e-mail e no gerenciador) e informa, quando nega o aumento de limite, o próximo passo pelo alerta de conta. Ou seja, o mesmo canal que traz a resposta do cliente traz o sinal de que algo precisa de atenção.

Como configurar o webhook, passo a passo?

1. 1
   Criar um endereço HTTPS

   O endpoint precisa de certificado TLS válido e bem instalado. Certificado autoassinado não é aceito. Existe a opção de mTLS para mais segurança.

2. 2
   Responder à verificação

   A Meta faz uma requisição GET com hub.mode igual a subscribe, um hub.challenge aleatório e o seu hub.verify_token. Se o token bate com o que você guardou, responda 200 e devolva o valor do challenge. Só depois disso a Meta começa a enviar eventos.

3. 3
   Cadastrar o endereço no painel

   No painel do app da Meta, em WhatsApp e Configuration, informe a URL de retorno (callback) e o token de verificação.

4. 4
   Assinar os campos

   Depois da verificação, aparece a lista de campos. Marque o campo messages (respostas e status) e os campos da conta que o seu time precisa acompanhar.

5. 5
   Validar a assinatura de cada aviso

   Cada POST traz o cabeçalho X-Hub-Signature-256 no formato sha256=hash. Calcule o HMAC-SHA256 do corpo bruto com o segredo do app e compare. Se não bate, descarte.

6. 6
   Responder 200 e tratar depois

   Devolva 200 logo que validar e processe a fila em seguida. Resposta diferente de 200 faz a Meta tentar de novo.

Quais regras técnicas o webhook precisa cumprir?

• Repetição: se o seu endpoint falha ou responde diferente de 200, a Meta tenta de novo por até 7 dias, com frequência decrescente. Isso gera avisos duplicados, então o tratamento precisa ser idempotente (guardar o identificador da mensagem e do status e ignorar repetidos).
• Tamanho: o corpo pode ter até 3 MB.
• Lotes: um envio pode reunir até 1.000 atualizações, mas a Meta não garante lote, então trate cada requisição como independente.
• Permissões: o campo messages exige a permissão whatsapp_business_messaging; os demais avisos de conta exigem whatsapp_business_management.
• Segurança: além da assinatura, há mTLS. A lista de IPs da Meta muda de tempos em tempos, por isso o mTLS é a opção mais estável do que liberar IP por IP.

Para testar sem perder tempo, use o envio de teste do painel do app e depois uma mensagem real para um número seu. O passo a passo de teste está em como testar um webhook.

Como o webhook transforma o disparo em atendimento?

Quando o cliente responde, o webhook entrega a mensagem ao seu sistema, e a conversa abre a janela de 24 horas, na qual a empresa pode responder sem template (veja janela de 24 horas do WhatsApp). A parte que decide se a campanha vira venda é o que acontece em seguida: quem atende, em quanto tempo e com qual resposta pronta.

1. A resposta entra pelo webhook e é associada ao contato pelo número do cliente.
2. O CRM aplica a regra de fila: campanha, região ou tipo de produto.
3. O contato recebe a etiqueta da campanha, para medir depois.
4. Pedidos de saída (parar de receber) são registrados na hora e o contato sai das próximas listas.
5. Os status viram o relatório: enviadas, entregues, lidas, falhas por motivo.

Se você ainda não tem CRM, a AD PRO implementa: veja implementação de CRM. E para preparar o time que recebe as respostas, leia como atender as respostas do disparo.

[ ] 1. Endereço em HTTPS com certificado válido (não autoassinado)
[ ] 2. Verificação GET respondida com 200 e o challenge devolvido
[ ] 3. Campo messages assinado
[ ] 4. App no modo Live
[ ] 5. Assinatura X-Hub-Signature-256 validada (aviso com assinatura errada é descartado)
[ ] 6. Mensagem de teste enviada para um número interno: apareceram sent, delivered e read?
[ ] 7. Resposta do número interno chegou ao CRM, na fila certa?
[ ] 8. Aviso repetido (mesmo id) não duplica contato nem relatório
[ ] 9. Falha simulada (número inexistente): o erro foi gravado com código?
[ ] 10. Quem é avisado se o endpoint cair: ____________

Exemplo de campos de um aviso de status (valores fictícios):
{ id: 'wamid.EXEMPLO', status: 'delivered', timestamp: '1760000000', recipient_id: '5511999990000' }