Webhooks do WhatsApp: eventos, segurança e novas tentativas

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Como escrevo um handler confiável?

Faça três coisas, nesta ordem: armazene o evento bruto, confirme com um 2xx e depois processe de forma assíncrona. O handler abaixo segue o padrão da nossa documentação.

import express from "express";

const app = express();

// Capture o corpo bruto para guardá-lo exatamente como foi recebido.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // o armazenamento falhou: deixe o evento ser reenviado
    }
    res.sendStatus(200);          // confirme rápido
    queue.publish("status-events", req.body); // faça o trabalho de verdade em outro lugar
  },
);

// Worker: processamento idempotente
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // mapeie por canal
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // mensagem desconhecida: registre e investigue
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // duplicado ou desatualizado

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # o armazenamento falhou: deixe o evento ser reenviado
    queue.publish("status-events", raw)  # processe de forma assíncrona
    return "", 200               # confirme rápido

Os objetos db e queue são o seu próprio armazenamento e fila de jobs. O mapa rank é o que torna o processamento idempotente: um evento duplicado ou desatualizado não representa um avanço, então é ignorado.

Regras para um handler confiável

• Responda em poucos segundos. Não faça trabalho pesado antes de responder.
• Devolva 2xx apenas depois que o evento estiver armazenado. Se o armazenamento falhar, devolva 5xx.
• Deduplique pelo ID da mensagem. O mesmo status pode chegar mais de uma vez.
• Nunca reenvie uma mensagem a partir do handler. Decida sobre novas tentativas em um job separado, depois de conferir o status.
• Guarde o corpo bruto para diagnóstico e para reproduzir eventos depois de uma correção.

Como protejo um webhook do WhatsApp?

Depende de quem envia ao seu endpoint. A Meta assina os webhooks que envia a apps registrados nela. A especificação da API da OmniChannels.ai não define cabeçalho de assinatura de webhook, então não espere por um.

Para o esquema da Meta, a documentação dela diz para gerar um hash HMAC-SHA256 do payload JSON usando o segredo do seu app e compará-lo com o valor após sha256= no cabeçalho X-Hub-Signature-256. O próprio HMAC é definido na RFC 2104. Calcule-o sobre os bytes brutos, não sobre um objeto serializado de novo, e compare em tempo constante.

Para o nosso endpoint:

• Use apenas HTTPS, com um certificado válido.
• Use um caminho longo e imprevisível e troque-o se vazar.
• Valide o formato do corpo e rejeite qualquer coisa inesperada.
• Trate os eventos como notificações. Antes de uma ação irreversível, como um reembolso ou um bloqueio por fraude, confirme o estado com uma consulta.

O que acontece quando a entrega falha?

As novas tentativas dependem de quem envia. A documentação da Meta diz que ela repete uma entrega com falha com frequência decrescente por até 7 dias, o que pode gerar notificações duplicadas. Esse é um motivo para ser idempotente mesmo que você raramente veja duplicatas. Para eventos da nossa plataforma, confirme o comportamento de novas tentativas com o seu engenheiro de onboarding em vez de presumir que seja igual ao da Meta.

De todo modo, construa pensando tanto em perda quanto em duplicação: seu endpoint pode estar fora do ar durante um deploy, e uma regra de firewall pode descartar requisições silenciosamente.

Como recupero eventos perdidos?

Consulte o lote, não reenvie a mensagem.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id é o ID devolvido pela chamada de envio, e page começa em zero. Execute uma conciliação noturna que leia os lotes do dia anterior e preencha as lacunas.

Checklist de solução de problemas

1. A URL está configurada na conta ou subconta correta?
2. O endpoint é acessível por HTTPS com um certificado válido?
3. Ele responde 2xx rapidamente ou dá timeout?
4. Uma regra de firewall ou de WAF está bloqueando as requisições?
5. Você registra o corpo bruto antes de fazer o parsing, para que um erro de parser não esconda o evento?

Exemplo prático: o pipeline de notificações de uma varejista

A "Souq Rafiq" (sintética), uma varejista dos Emirados Árabes Unidos, envia atualizações de pedidos por WhatsApp e quer um status preciso na sua ferramenta de pedidos.

1. Os pedidos são enviados com sendbulk, e o batchId é guardado no pedido. Veja enviar uma mensagem de WhatsApp por API.
2. O endpoint do webhook grava cada evento em uma tabela e depois devolve 200.
3. Um worker ordena os status e atualiza o estado da mensagem do pedido.
4. Eventos FAILED criam uma tarefa para o suporte com o motivo, e um fallback por SMS é avaliado conforme o fallback entre canais.
5. As mensagens recebidas de clientes são encaminhadas à caixa de entrada compartilhada para que os atendentes respondam dentro da janela.
6. Um job noturno chama o bulk-insights para os lotes de ontem e corrige o que tiver sido perdido.

Quais são os erros comuns?

• Trabalho pesado antes de responder, que causa timeouts e entregas repetidas.
• Confirmar antes de armazenar, o que perde eventos quando o armazenamento falha.
• Confiar na ordem. Um SENT tardio sobrescrevendo DELIVERED.
• Programar com base no payload ilustrativo em vez de eventos reais.
• Serializar o JSON de novo antes de verificar uma assinatura, o que altera os bytes.
• Reenviar a partir do handler, o que pode gerar loops.
• Limites: este guia descreve o comportamento documentado por nós. A política de novas tentativas e os campos do payload da sua conta devem ser confirmados durante o onboarding.

Como a OmniChannels.ai ajuda

A OmniChannels.ai envia por push status de entrega e mensagens recebidas de WhatsApp, SMS, RCS e outros canais ao seu webhook em um único formato normalizado, com webhooks separados por subconta para revendedores. A BroadNet é uma Meta Business Solution Provider oficial, então os requisitos de webhook da própria Meta são tratados por nós, e você trabalha com a nossa API. Leia a referência de webhooks e a documentação da API de WhatsApp ou veja como os eventos aparecem na caixa de entrada compartilhada.