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:
- O que acontece se o evento chegar duas vezes?
- O que acontece se ele chegar fora de ordem?
- Onde eu vejo os eventos que falharam?
- Quem é avisado quando a fila para?
- 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.
