Quando uma automação depende de WhatsApp, é comum começar pela pergunta errada: “qual endpoint eu chamo?”. A pergunta mais importante vem antes: o que acontece com o evento depois que ele sai da API?

Uma mensagem enviada percorre um caminho. Ela é recebida, validada, enfileirada, processada e só então entregue. Cada etapa pode falhar ou atrasar. Se o seu sistema trata a resposta inicial como confirmação de entrega, ele está otimista demais.

O que o aceite realmente significa

APIs costumam responder algo como 202 Accepted quando a requisição entrou na fila. Isso é útil: informa que o pedido foi compreendido. Não informa que a mensagem chegou ao destino.

Trate o aceite como o início de um acompanhamento, não como o fim. O estado final precisa vir por evento, consulta ou ambos.

Eventos são fatos, não comandos

Um webhook bem modelado conta o que aconteceu: uma mensagem foi recebida, uma instância mudou de estado, uma chamada terminou. Ele não deve carregar a decisão de negócio.

{
  "event": "message.received",
  "instance": "atendimento-01",
  "message": {
    "id": "msg_exemplo_123",
    "from": "5511999999999",
    "type": "text"
  },
  "timestamp": "2026-03-26T14:32:10Z"
}

O exemplo é ilustrativo. O ponto é separar evento de interpretação: quem decide criar um cartão, abrir um atendimento ou responder automaticamente é o seu sistema, com as suas regras.

Idempotência: a mesma mensagem duas vezes

Redes falham, retries acontecem e o mesmo evento pode chegar mais de uma vez. Sem idempotência, isso vira dois cartões, duas notas ou duas mensagens para o cliente.

Use o identificador do evento ou da mensagem como chave. Antes de processar, verifique se aquele registro já foi tratado. Guardar o histórico de entregas também ajuda a diagnosticar o que realmente passou.

Retry, fila e backoff

Um webhook que falha não deveria desaparecer. A arquitetura precisa prever:

  • nova tentativa com intervalo crescente;
  • limite de tentativas e um estado de falha visível;
  • fila para absorver picos;
  • registro do que foi entregue e do que ficou pendente.

Se o seu receptor responde bem mas demora para processar, você só moveu o problema para dentro. Confirme rápido e processe de forma controlada.

Segurança e rastreabilidade

Uma URL pública de webhook precisa de cuidado. Valide a origem, use segredo compartilhado quando disponível, rejeite payloads inesperados e não registre tokens em log. Para auditoria, guarde horário, evento, status e identificador — sem dados sensíveis desnecessários.

Se o seu sistema depende do webhook, ele precisa saber o que fazer quando o webhook falha.

Antes de ligar a automação

Responda a estas perguntas:

  1. O que acontece se o evento chegar duas vezes?
  2. O que acontece se ele chegar fora de ordem?
  3. Onde eu vejo os eventos que falharam?
  4. Quem é avisado quando a fila para?
  5. Como eu reprocesso um evento sem duplicar efeitos?

A StackZap é infraestrutura self-hosted para conectar WhatsApp a sistemas e automações; ela não é uma API oficial do WhatsApp. Antes de colocar qualquer fluxo em produção, vale avaliar as políticas aplicáveis ao seu caso.

Automação boa não é a que nunca falha. É a que falha de um jeito que você consegue enxergar, corrigir e repetir sem estragar o que já funcionou.