Evolution API: diagnosticar webhooks que não chegam

Resposta rápida

Divida o problema em duas perguntas: a Evolution API conseguiu fazer a requisição HTTP e o consumidor aceitou/processou o payload? Verifique URL, resolução DNS, TLS, código HTTP, autenticação e logs dos dois lados. Um painel vazio não prova que o webhook não foi enviado.

Veja a infraestrutura: VPS para Redis no Brasil para colocar este projeto no ar.

Confirme a URL e o contrato

Revise endpoint, método, caminho, headers e formato esperado. Evite URLs temporárias ou que dependam de uma sessão local. Se o consumidor exige um segredo, valide como header ou assinatura sem imprimir o valor nos logs.

Teste a rede do ponto de origem

A requisição precisa funcionar a partir do host/container que executa a API:

getent hosts automacao.exemplo.com
curl -vk -X POST https://automacao.exemplo.com/webhook/teste \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: diagnostico-001' \
  --data '{"event":"test","id":"diagnostico-001"}'

O -k serve apenas para diagnóstico de certificado; não use para mascarar TLS inválido em produção. Interprete o status: 2xx indica aceitação HTTP, 4xx aponta contrato/autorização e 5xx aponta falha no servidor receptor ou no caminho.

Correlacione logs

Registre um request ID sem dados pessoais e compare o horário nos logs da API, do proxy reverso e do consumidor. Procure timeout, erro de DNS, handshake TLS, limite de corpo e reinício do processo. Se o consumidor retorna 200 antes de processar uma fila, o evento pode falhar depois; observe também o worker.

Evite perda e duplicidade

Webhooks podem ser repetidos. O consumidor deve guardar um identificador do evento e processar de forma idempotente. Responda rapidamente e mova trabalho pesado para uma fila. Em caso de retry, uma operação já concluída não deve enviar a mesma mensagem duas vezes.

Segurança e operação

Use HTTPS válido, autenticação, limite de tamanho e rate limit. Não exponha banco ou Redis para receber webhook. Faça um teste com payload fictício e janela combinada; não dispare mensagens reais durante diagnóstico.

Uma infraestrutura estável reduz variáveis, mas não substitui logs. Conheça a VPS para Evolution API.

Checklist

• [ ] URL e contrato conferidos.
• [ ] DNS e TLS testados no ponto de origem.
• [ ] Status HTTP e corpo registrados.
• [ ] Logs correlacionados por request ID.
• [ ] Consumidor idempotente e protegido.

FAQ

200 OK garante que o evento foi processado?

Não. Garante apenas a resposta HTTP do endpoint. Confirme a fila e o processamento posterior.

Posso testar com meu número real?

Prefira payload fictício ou ambiente de teste para evitar mensagens e efeitos colaterais.

Matriz rápida de diagnóstico

Se não há registro no proxy, investigue DNS, rota e TLS. Se há 4xx, confira autenticação e contrato. Se há 2xx sem efeito, acompanhe fila e processamento do consumidor. Se há 5xx, preserve o horário, request ID e corpo mínimo para reproduzir. Essa ordem evita alterar a Evolution API, o Nginx e o fluxo de automação simultaneamente, o que apaga a evidência da causa original.