Webhook não funciona? O roteiro de 7 passos para achar onde o dado parou

O formulário foi enviado, o cliente jura que preencheu, e o lead não apareceu no CRM. É o chamado mais comum depois de uma integração nova, e quase sempre o problema é pequeno: uma letra no endereço, um método trocado, uma vírgula sobrando no JSON. O truque é procurar na ordem certa, do mais simples para o mais raro, em vez de refazer a integração inteira.

Se a palavra webhook ainda é nova para você, comece por o que é webhook. Aqui o foco é diagnóstico. O exemplo usa a Clínica Ipê, uma empresa fictícia, cujo formulário de agendamento deveria criar leads no CRM e não criava.

O que preparar antes de testar?

Tenha em mãos três coisas: o evento que deveria ter disparado o webhook, o endereço de destino e algum lugar onde ver o que chegou. Sem isso, o teste vira adivinhação.

• Um evento de teste que você controle: envie o formulário você mesmo, com um nome claramente de teste, como 'Teste Silva'. Assim o lead de teste se distingue do real.
• O endereço exato de destino: copie e cole, não digite.
• Um lugar para ver a requisição: o histórico de execuções da ferramenta que recebe (no n8n, a aba Executions) ou o registro do sistema que envia.
• Dados de teste que não são de cliente real: em ferramentas públicas de teste, qualquer pessoa que tenha o endereço pode ver o que chegou. Não cole dado pessoal verdadeiro ali.

Quais são os 7 passos para achar por que o webhook não chega?

A ordem é: URL, método, formato, autenticação, resposta 200, reenvio e log. Cada passo elimina uma família de causas, e você só avança quando o anterior estiver conferido.

1. 1
   1. URL: o endereço está certo e é o de produção?

   Compare o endereço configurado no sistema que envia com o do que recebe, caractere por caractere, sem espaço no começo ou no fim e com https. Se o receptor é o n8n, há dois endereços: o de teste e o de produção. Segundo a documentação do n8n, o de teste só fica ouvindo por um período curto, cerca de 120 segundos, depois que você manda escutar um evento de teste, e o de produção só recebe quando o fluxo está publicado e ativo. O erro mais frequente que vemos é o formulário apontando para o endereço de teste, que já não está ouvindo.

2. 2
   2. Método: o envio é POST?

   Webhook com corpo de dados costuma ser POST. Se o receptor espera POST e recebe GET, ou o contrário, a resposta é um erro de método (405) ou nada acontece. Confira a configuração dos dois lados.

3. 3
   3. Formato: o corpo é um JSON válido e vem com o tipo certo?

   Dois defeitos clássicos: uma vírgula sobrando ou aspas faltando, que deixam o JSON inválido, e o cabeçalho Content-Type ausente ou diferente de application/json, que faz o receptor não ler o corpo. Cole o corpo em um validador de JSON e confira o cabeçalho.

4. 4
   4. Autenticação: a chave está sendo enviada e é a mesma?

   Se o receptor exige um token ou um segredo em cabeçalho, uma chave ausente, vencida ou com espaço extra resulta em 401 ou 403. Compare a chave dos dois lados e confirme o nome do cabeçalho.

5. 5
   5. Resposta: o receptor devolve 200 rápido?

   Se o receptor demora para responder porque faz tudo antes, o emissor pode desistir por tempo esgotado e tentar de novo, o que gera duplicidade. O desenho certo é responder 200 ao receber e processar em seguida. Na documentação dos webhooks do WhatsApp, a Meta diz que uma resposta diferente de 200 faz ela tentar novamente com frequência decrescente por até 7 dias.

6. 6
   6. Reenvio: o mesmo evento funciona se enviado outra vez?

   Depois de corrigir algo, reenvie o mesmo evento de teste. Se funcionar agora, o problema estava na parte corrigida. Se funcionar só de vez em quando, desconfie de tempo de resposta ou de limite de uso no receptor. Confira também se o reenvio criou dois leads, o que indica falta de uma chave para reconhecer repetição.

7. 7
   7. Log: o que o registro diz sobre essa execução?

   Abra o registro de execuções e leia a primeira mensagem de erro, não a última. Ela costuma apontar o campo ou o nó que falhou. Se nada aparece no receptor, a requisição nem chegou, e o problema está nos passos 1 e 2 ou na rede. Se aparece e falhou, está nos passos 3 a 5.

O que cada código de resposta está dizendo?

O código de status que o receptor devolve é a pista mais barata que existe. Quando o emissor mostra o código na tela de entregas, ele resume o problema em três dígitos.

O significado desses códigos está no padrão do protocolo HTTP (RFC 9110; o 429 vem de uma norma complementar, a RFC 6585). Se o seu emissor mostra apenas 'falhou', peça a tela de detalhes da entrega: sem o código, o diagnóstico fica muito mais longo.

Como mandar um webhook de teste na mão?

Um comando de teste isola o receptor do emissor. Se o dado chega quando você manda na mão, o problema está no emissor; se não chega, está no receptor ou na rede.

curl -i -X POST "https://SEU-ENDERECO/webhook/novo-lead" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SUA-CHAVE-DE-TESTE" \
  -d '{"nome":"Teste Silva","telefone":"+5511999990000","origem":"teste-manual"}'

Como ler o resultado:
- A primeira linha mostra o código de status (200, 404, 401...).
- Se a primeira linha for 200 e o lead não aparecer no CRM, olhe o log do fluxo.
- Se for 404, revise a URL e se o fluxo está ativo.
- Se for 401 ou 403, revise a chave.
- Troque SEU-ENDERECO e SUA-CHAVE-DE-TESTE pelos valores reais. Nunca publique a chave verdadeira.

Quem não usa o terminal pode fazer o mesmo em qualquer cliente gráfico de requisições: escolha POST, cole a URL, ponha o cabeçalho Content-Type e cole o corpo em JSON. A lógica de leitura do resultado é a mesma.

Um caso resolvido: o formulário da Clínica Ipê

Na Clínica Ipê (fictícia), o formulário de agendamento enviava os dados para um fluxo no n8n que criava o lead no CRM. Passou uma semana sem lead novo. Seguindo os 7 passos:

1. URL: o formulário apontava para o endereço de teste do fluxo, que só ouve por poucos minutos. Causa encontrada no primeiro passo.
2. Correção: trocar pelo endereço de produção e publicar o fluxo.
3. Reenvio: o formulário de teste gerou o lead, mas apareceram dois cadastros iguais, porque o formulário também reenviava em caso de lentidão.
4. Segunda correção: o fluxo passou a procurar o telefone antes de criar e a responder 200 antes de gravar, o que acabou com a duplicidade.
5. Aviso: a clínica ganhou um alerta para o responsável sempre que o fluxo falhar, para o problema não ficar uma semana escondido.

E se os 7 passos não resolverem?

Se todos os passos estão corretos e o dado ainda não chega, junte as evidências e peça ajuda com elas. Um chamado com evidência é resolvido em uma conversa; um chamado de 'não funciona' vira dez perguntas.

Qual sistema envia e qual recebe:
O que deveria acontecer (em uma frase):
Quando começou a falhar e o que mudou antes (nova URL, nova chave, novo plano, novo campo):
O evento de teste que você usou (data, hora e nome do lead de teste):
O código de status que apareceu na entrega:
A primeira mensagem de erro do log (copie o texto):
O corpo enviado (apague dados pessoais reais antes de colar):
Já reenviou o mesmo evento? O resultado foi igual ou diferente?
Quem precisa ser avisado quando voltar a funcionar:

Para prevenir o próximo chamado, deixe um lead de teste rodando toda semana e um alerta de falha. Se a origem do problema era a planilha que alimenta o funil, veja também integrar Google Sheets com CRM.