Como Configurar Webhook do WhatsApp Business com Node.js: Tutorial 2026
O webhook é o coração de qualquer integração com a API do WhatsApp Business. Ele é o endpoint HTTP que a Meta chama toda vez que alguém envia uma mensagem para o seu número. Este tutorial cobre desde a verificação do webhook até o processamento de mensagens em produção com Node.js.
O que é um webhook e por que ele é necessário
A API do WhatsApp Business funciona no modelo push: quando uma mensagem chega, a Meta envia um POST para o URL que você registrou no Meta Business Manager. Sem um webhook funcionando e acessível pela internet, você não recebe nenhuma mensagem.
O webhook precisa ser um endpoint HTTPS com certificado SSL válido. URLs localhost não funcionam em produção, mas ferramentas como ngrok permitem expor o localhost durante o desenvolvimento.
Passo 1: configurar o projeto Node.js
Crie um projeto novo com Express para servir o webhook. O servidor precisa responder ao método GET para a verificação inicial e ao método POST para as mensagens recebidas.
- mkdir whatsapp-webhook && cd whatsapp-webhook
- npm init -y && npm install express dotenv
- Crie o arquivo .env com VERIFY_TOKEN=seu_token_secreto e WHATSAPP_TOKEN=seu_token_de_acesso
- Crie o arquivo index.js com o servidor Express básico na porta 3000
- npm install -g nodemon para desenvolvimento com reload automático
Passo 2: implementar a verificação do webhook
Quando você registra o webhook no Meta Business Manager, a Meta faz uma requisição GET para verificar que o endpoint é seu. Ela envia três parâmetros: hub.mode, hub.verify_token e hub.challenge. Seu servidor deve verificar se o token bate e responder com o valor de hub.challenge.
- Rota: GET /webhook
- Extraia os query params: req.query['hub.mode'], req.query['hub.verify_token'], req.query['hub.challenge']
- Se mode === 'subscribe' e verify_token bate com o seu, responda res.status(200).send(challenge)
- Caso contrário, responda res.sendStatus(403)
Passo 3: processar mensagens recebidas
O payload POST da Meta é um objeto JSON com a estrutura entry[0].changes[0].value. Dentro dele você encontra messages (array de mensagens recebidas), contacts (informações do remetente) e metadata (número de telefone do destinatário).
Nem todo POST contém mensagens. Status de entrega e leitura também chegam pelo webhook. Verifique sempre se entry[0].changes[0].value.messages existe antes de processar.
Passo 4: enviar respostas via API
Para responder a uma mensagem, faça um POST para https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages com o token de acesso no header Authorization e o corpo com o tipo e conteúdo da mensagem.
O campo messaging_product deve ser 'whatsapp', o campo to deve ser o número do destinatário no formato internacional sem o + (ex: 5511999999999) e o campo text.body contém o texto da resposta.
Passo 5: deploy em produção
Para produção, você precisa de um servidor com IP fixo e HTTPS. As opções mais comuns são Railway, Render, Fly.io ou uma VPS como a DigitalOcean. Configure variáveis de ambiente, certificado SSL automático (Let's Encrypt) e um processo manager como PM2.
- Railway: deploy direto do GitHub, SSL automático, plano free generoso
- Render: similar ao Railway, boa documentação para Node.js
- Fly.io: mais controle, pode rodar em múltiplas regiões
- VPS com Nginx: mais trabalho de configuração, mais flexibilidade
Perguntas frequentes
Por que meu webhook não está recebendo mensagens?
As causas mais comuns são: URL não acessível pela internet (localhost sem ngrok), certificado SSL inválido, token de verificação errado no Meta Business Manager ou o webhook não está registrado no app correto. Verifique os logs do Meta no Business Manager em Configurações do App.
Como testar o webhook sem subir para produção?
Use ngrok (ngrok http 3000) para expor seu localhost. O ngrok gera uma URL HTTPS pública que você registra temporariamente no Meta Business Manager. Também é possível usar a ferramenta de teste de webhook do próprio Meta Business Manager.
O webhook precisa responder em quanto tempo?
A Meta espera uma resposta 200 em até 20 segundos. Se o processamento demorar mais, responda 200 imediatamente e processe de forma assíncrona em background. Respostas lentas ou erros 5xx podem causar retry automático e até desativação do webhook.
Como lidar com múltiplas mensagens simultâneas?
Use uma fila de processamento (Bull com Redis, ou AWS SQS) para garantir que mensagens em alta concorrência sejam processadas na ordem correta. Para volumes baixos, o processamento síncrono em Express já resolve.
Preciso validar a assinatura dos webhooks da Meta?
Sim, em produção. A Meta assina cada requisição com HMAC-SHA256 usando o App Secret. Valide o header x-hub-signature-256 antes de processar para garantir que o payload veio realmente da Meta.