Webhooks são o “sistema nervoso” da automação no WhatsApp: mensagem recebida, status de entrega, leitura, falhas e atualizações chegam por eventos. O problema é que webhooks não são transações: eles podem chegar duplicados, fora de ordem, com atraso — e, se você não proteger o endpoint, qualquer um pode tentar disparar ações dentro do seu CRM.
Neste artigo, você vai aprender um modelo prático para operar webhooks do WhatsApp com segurança (assinatura e autenticação), confiabilidade (idempotência e retries) e reprocessamento seguro (DLQ + auditoria).
O básico: o que pode dar errado com webhooks
- Entrega duplicada: o mesmo evento chega mais de uma vez (ou você recebe reenvio por falha).
- Fora de ordem: status “lido” chega antes do “entregue” em alguns cenários.
- Timeout: seu endpoint demora e o provedor reenvia.
- Assinatura ignorada: alguém forja payload e cria/fecha tickets, altera tags, dispara campanhas.
Verificação: validação do webhook (GET) e assinatura (POST)
Quando você configura webhooks em provedores do ecossistema Meta/WhatsApp, geralmente existem dois momentos:
- Verificação inicial (GET): o servidor precisa responder um desafio (ex.:
hub.challenge), validando um token. - Eventos (POST): o payload chega com cabeçalhos de autenticação/assinatura para confirmar que veio do provedor.
Uma referência prática (com verificação via token e checagem de assinatura no header x-hub-signature-256) aparece na documentação do SDK Node da WhatsApp Business Platform. https://whatsapp.github.io/WhatsApp-Nodejs-SDK/api-reference/webhooks/start/
Regra importante: verifique assinatura com o corpo “raw”
Assinaturas HMAC são calculadas sobre os bytes do corpo. Se seu framework parsear/normalizar o JSON antes (mudando espaços, ordem, encoding), a verificação pode falhar. Esse é um ponto comum em implementações de webhooks e aparece com frequência em documentações de referência (por exemplo, a Stripe recomenda verificação usando o payload bruto para evitar falhas e ataques de replay). https://docs.stripe.com/webhooks/signatures
Idempotência: como impedir efeitos duplicados
O objetivo da idempotência é simples: processar o mesmo evento uma vez, mesmo que ele chegue repetido. Para isso, você precisa de uma chave estável por evento + uma trava persistente.
Padrão recomendado (independente de stack)
- Escolha uma chave de idempotência: idealmente um event_id do provedor (quando existir). Se não existir, use hash de campos estáveis (tipo + message_id + timestamp + origem).
- Crie uma tabela/coleção “processed_events” com índice único na chave.
- Faça o handler ser “upsert-first”: tente registrar a chave; se já existir, ignore o processamento.
Por que índice único é melhor que “if exists”
Em concorrência, dois workers podem ler “não existe” ao mesmo tempo e processar duplicado. O índice único faz a regra valer no banco (o que realmente impede duplicação).
Retries e backoff: como responder rápido e processar com segurança
Seu endpoint deve responder rápido (200/204) e empurrar o trabalho pesado para um pipeline interno. Um modelo prático:
- Camada 1 (ingestão): valida assinatura, registra evento bruto (raw), retorna 200 em poucos ms.
- Camada 2 (processamento): worker processa, aplica idempotência e atualiza CRM/tickets.
- Camada 3 (retries): em falhas temporárias, reprocessa com backoff e limite.
Quando usar DLQ (dead-letter queue)
Se um evento falha repetidamente (ex.: payload inesperado, regra quebrada, dependência fora do ar), jogue em uma DLQ. Isso evita “loop infinito”, protege o throughput e cria um ponto único de triagem.
Observabilidade: sem logs e métricas, você voa no escuro
Em webhooks, “funciona na minha máquina” não existe. Instrumente:
- event_id / correlation_id por request
- latência do endpoint (p95/p99)
- taxa de duplicados (idempotência acionada)
- erros por tipo de evento (schema, validação, dependência)
- tamanho de fila e tempo em fila
Modelo de arquitetura: WhatsApp → Webhook → CRM/Automação
Um desenho simples e robusto para automações de WhatsApp com CRM:
- Webhook receiver: valida assinatura + grava evento bruto.
- Event store: guarda payload raw + headers + timestamp + resultado.
- Router: decide qual fluxo executar (atendimento, disparo, tag, funil).
- Workers: executam ações (criar ticket, atualizar etapa, notificar operador, etc.).
- Reprocessor: reexecuta eventos da DLQ com versão de regra corrigida.
Segurança além da assinatura
- Rate limiting e WAF (principalmente em endpoints públicos).
- Allowlist de IPs quando o provedor suporta (não confie só nisso).
- Segredos por ambiente (dev/staging/prod) e rotação periódica.
- Comparação segura de assinatura (evitar timing attacks). Um exemplo de recomendação de header e HMAC aparece nos guias do GitHub para webhooks com
X-Hub-Signature-256. https://docs.github.com/developers/webhooks-and-events/webhooks/securing-your-webhooks
Como a Sendfy ajuda a organizar webhooks e automações no WhatsApp
Se você quer sair do “callback em produção” e operar webhooks com maturidade, a Sendfy ajuda a estruturar:
- Captura e roteamento de eventos para funis e atendimento.
- Regras de idempotência e rastreabilidade em automações.
- Integrações por webhooks com CRM e sistemas internos.
Quer ver um fluxo robusto rodando? Conheça a Sendfy.
Checklist rápido para seu endpoint de webhooks
- Validar verificação (token) no GET (quando aplicável).
- Verificar assinatura no POST usando corpo raw.
- Persistir evento bruto + headers + status de processamento.
- Implementar idempotência com chave estável + índice único.
- Separar ingestão rápida de processamento assíncrono.
- Ter retries com backoff + DLQ e reprocessamento.
- Instrumentar logs e métricas (latência, duplicados, erros).