WACrew

Guia

Webhook do WhatsApp: como sua aplicação fica sabendo de mensagem nova

Webhook é a chamada HTTP que avisa sua aplicação quando chega mensagem ou muda o status de um envio no WhatsApp. Como funciona na API oficial e nas não oficiais.

Atualizado em 1 min de leitura
Nesta página
  1. Como aparece na prática
  2. Erro comum
  3. Perguntas frequentes

Webhook do WhatsApp é uma chamada HTTP que o provedor faz para um endereço seu sempre que algo acontece: chegou mensagem, a mensagem foi entregue ou lida, um envio falhou. Em vez de perguntar "tem novidade?" a cada segundo, sua aplicação é avisada.

Como aparece na prática

Na API oficial (Cloud API da Meta), você cadastra uma URL de callback e um token de verificação no app da Meta. A Meta faz um GET de verificação (com hub.mode, hub.verify_token e hub.challenge) e, depois, manda um POST com JSON para cada evento.

Nas APIs não oficiais, como Evolution API, WAHA ou Z-API, o próprio servidor que roda a sessão do WhatsApp dispara o POST para a sua URL. O formato muda de uma para outra.

O WACrew não depende de webhook para o agente: o painel publica os eventos por SSE (/api/events), e o plantão do agente escuta essa conexão e é acordado a cada mensagem. Detalhes em webhook do WhatsApp na prática.

Erro comum

Fazer trabalho pesado dentro da resposta do webhook. O provedor espera um 200 rápido; se a sua rota demora (chama a IA, consulta banco, envia resposta), ele tenta de novo e você processa a mesma mensagem duas vezes. Responda na hora, guarde o evento numa fila e trate depois. E use o id da mensagem para ignorar repetidos.

Perguntas frequentes

Webhook precisa de HTTPS? Na API oficial, sim. Nas outras, é o recomendado.

Dá para testar webhook no computador? Dá, com um túnel (Cloudflare Tunnel, ngrok) apontando para a sua porta local.

O n8n recebe webhook do WhatsApp? Recebe, com o nó Webhook; veja n8n com agente de IA no WhatsApp.

Em inglês: webhook.