Evolution API: diagnosticar webhooks que não chegam

--- queue_position: 29 title: "Evolution API: diagnosticar webhooks que não chegam" slug: evolution-api-diagnosticar-webhooks site_key: host-yousecure canonical: https://yousecure.io/blog/evolution-api-diagnosticar-webhooks category: evolution-api-troubleshooting cluster: whatsapp-webhooks search_intent: informacional-comercial funnel_stage: fundo author: "Host You Secure Team" created_at: "2026-09-09T11:29:43-03:00" planned_scheduled_at: null status: queued-review meta_description: "Veja como investigar webhooks da Evolution API: URL, DNS, TLS, status HTTP, logs, autenticação e idempotência." excerpt: "Quando o webhook não chega, separe DNS, TLS, rota, autenticação e processamento antes de alterar vários componentes ao mesmo tempo." quick_answer: "Teste a URL a partir do mesmo servidor da Evolution API, confira o status HTTP e o corpo recebido, depois correlacione horário, request ID e logs do consumidor." featured_image: images/29-evolution-webhooks.png featured_image_alt: "Evento de mensagem atravessando um gateway de API até um servidor de automação" tags: [evolution-api, webhooks, whatsapp-api, troubleshooting, n8n] evidence_type: reproducible_procedure evidence_environment: Evolution API e consumidor de webhook em endpoints HTTPS controlados evidence_procedure: "Enviar payload de teste, conferir DNS/TLS, capturar logs do servidor e repetir com request id." evidence_observed_result: "A correlação por horário e status reduz o diagnóstico por tentativa e erro." evidence_limitation: "Campos e rotas variam conforme a versão e a configuração do projeto." information_gain: "Diferencia entrega HTTP de processamento posterior no consumidor." primary_cta: "Ver VPS para Evolution API" landing: /vps-evolution-api-brasil --- # 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. ## 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: ```bash 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](https://yousecure.io/vps-evolution-api-brasil). ## 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.

Veja a infraestrutura: VPS para n8n + Evolution API para colocar este projeto no ar.