Webhooks no WhatsApp sem caos: filas, DLQ e observabilidade na prática

Quando sua operação no WhatsApp começa a depender de eventos (mensagem recebida, status, pagamentos, CRM, formulários), webhooks viram o “sistema nervoso”. O problema é que, sem uma arquitetura mínima, eles também viram a principal fonte de dor: duplicidade, perda de eventos, picos derrubando o atendimento e bugs difíceis de rastrear.

Neste guia, você vai ver um modelo prático para tratar webhooks no WhatsApp com fila, DLQ (dead-letter queue), idempotência e observabilidade — para escalar automações e CRM sem comprometer a experiência do cliente.

Por que webhooks “quebram” em produção

Em ambientes reais, três coisas acontecem ao mesmo tempo:

• Picos: campanhas, lançamentos, horário comercial e sazonalidade.
• Dependências lentas: CRM, ERP, gateways de pagamento, APIs externas.
• Falhas intermitentes: timeouts, DNS, limites de rate, deploys.

Se você processa tudo “na hora” (sincrono) no endpoint do webhook, você inevitavelmente cria gargalos e perda de eventos.

O padrão certo: receber rápido, processar depois

Arquitetura recomendada (simples e eficiente):

• Webhook receiver: valida, normaliza e enfileira.
• Queue: absorve picos e mantém ordem/retentativa.
• Workers: processam em paralelo, com retries controlados.
• DLQ: guarda mensagens que falharam repetidamente para triagem.

Exemplo de fluxo (alto nível)

• Evento chega: “mensagem recebida”.
• Você responde HTTP 200 rapidamente (em milissegundos).
• O evento entra numa fila (SQS, RabbitMQ, Redis Streams etc.).
• Um worker classifica a intenção e decide a próxima ação (tag, etapa do funil, resposta automática, handoff).

Idempotência: o antídoto contra duplicidade

Na prática, provedores e integrações podem reenviar o mesmo evento (por retry automático, timeout ou inconsistência). Por isso, seu processamento precisa ser idempotente: se o mesmo evento chegar duas vezes, o resultado final não muda.

Como implementar idempotência (do jeito prático)

• Escolha uma chave por evento: event_id do provedor ou um hash estável do payload.
• Registre processamento em um storage rápido (Redis/DB) com TTL: “event_id já visto”.
• Proteja ações críticas (criar ticket, enviar cobrança, mudar etapa) com upsert ou travas por chave.

Uma referência clara sobre por que webhooks devem ser tratados com idempotência e assinaturas é a documentação de webhooks da Stripe. https://docs.stripe.com/webhooks

Retries com backoff: falha faz parte do sistema

Falhas intermitentes são normais. O objetivo não é “nunca falhar”, e sim falhar com controle. Um bom retry inclui:

• Backoff exponencial (ex.: 10s, 30s, 2min, 10min).
• Jitter para evitar picos sincronizados.
• Limite de tentativas para não “travar” a fila.

Quando NÃO fazer retry

• Erro 4xx por dados inválidos (ex.: campo obrigatório ausente): corrija o payload/regra.
• Erro de regra (ex.: contato bloqueado, consentimento ausente): trate como fluxo alternativo.

DLQ (dead-letter queue): onde os “casos raros” vivem

Sem DLQ, falhas difíceis somem (perda) ou travam sua fila (congestionamento). Com DLQ, você ganha:

• Auditoria: qual evento falhou, quando e por quê.
• Triagem: separar bug de dado ruim e de indisponibilidade.
• Reprocessamento: corrigiu a causa? Reenvie só o que precisa.

Se você usa AWS, a própria documentação de SQS cobre o conceito e o uso de DLQ. https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html

Assinaturas e segurança: valide o webhook

Todo endpoint público de webhook deve ter, no mínimo:

• Assinatura (HMAC) e verificação do header.
• Replay protection (timestamp + janela de tolerância).
• IP allowlist quando aplicável.
• Rate limiting para proteção básica.

<\/ul>

Para WhatsApp, comece pelo entendimento das políticas e dos eventos na WhatsApp Business Platform. https://developers.facebook.com/docs/whatsapp/

Observabilidade: sem métricas você voa no escuro

O que medir para webhooks “não virarem incêndio”:

• Taxa de entrada (req/min) e tamanho de fila.
• Latência: tempo do evento até virar ação (end-to-end).
• Erros por tipo (timeout, 4xx, 5xx, validação).
• Retries e DLQ: volume diário e principais causas.

<\/ul>

Logs com correlação

Padronize um correlation_id (ex.: conversation_id) para ligar o evento ao ticket no CRM e às automações. Isso acelera debug e atendimento.

Checklist rápido (copie e cole no seu runbook)

• Endpoint responde rápido (enfileira e retorna 200).
• Workers idempotentes (dedupe por event_id/TTL).
• Retries com backoff e limite.
• DLQ com triagem e reprocessamento.
• Assinatura e proteção contra replay.
• Métricas e alertas (fila, erro, latência).

<\/ul>

Como a Sendfy ajuda a operar webhooks e automações no WhatsApp

Se você quer conectar WhatsApp, CRM e integrações sem perder eventos nem contexto, a Sendfy ajuda com automações, organização de conversas e fluxos que crescem com a operação. Conheça a plataforma e veja como estruturar seu atendimento: https://sendfy.app

Próximo passo sugerido

Escolha um evento crítico (ex.: “lead pediu proposta”) e implemente o pipeline fila → worker → idempotência → métricas. Em 1 semana você já reduz duplicidade e ganha previsibilidade.