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

> Saber como testar um webhook poupa horas: confira, nesta ordem, a URL, o método, o formato do corpo, a autenticação, a resposta 200, o reenvio do mesmo evento e o log de execuções. A maioria das falhas está no primeiro ou no segundo passo, como endereço de teste usado em produção ou método errado. Cada passo abaixo diz o que olhar e como corrigir.

Página original: https://www.adprotecnologia.com.br/crm/blog/como-testar-webhook
Autor: AD PRO Tecnologia. Publicado em 2026-10-21.

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](https://www.adprotecnologia.com.br/crm/blog/o-que-e-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. 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. 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. 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. 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. 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. 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. 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.

**Códigos de resposta comuns em webhook, o que significam e o que fazer**

| Código | Em português | Causa provável | Correção |
| --- | --- | --- | --- |
| 200, 201 ou 204 | Recebido com sucesso | Nenhuma: o aviso chegou | Se o dado ainda não aparece no CRM, o problema está depois do recebimento: leia o log do fluxo |
| 301 ou 302 | O endereço foi redirecionado | URL com http em vez de https, ou endereço antigo | Use a URL final em https; em alguns clientes o redirecionamento transforma o POST em GET |
| 400 | Requisição malformada | JSON inválido ou campo obrigatório ausente | Valide o JSON e compare os campos com o esperado |
| 401 ou 403 | Sem permissão | Chave ausente, errada ou vencida | Confira o segredo e o nome do cabeçalho |
| 404 | Endereço não encontrado | URL digitada errado, fluxo desativado ou endereço de teste fora do ar | Copie a URL de produção e confirme que o fluxo está ativo |
| 405 | Método não permitido | GET onde se esperava POST, ou o contrário | Ajuste o método dos dois lados |
| 415 | Tipo de conteúdo não aceito | Falta Content-Type: application/json | Envie o cabeçalho certo |
| 422 | Dados entendidos, mas recusados | Valor em formato inesperado, como telefone sem DDD | Padronize o campo antes de enviar |
| 429 | Muitas requisições | Envio em rajada acima do limite do receptor | Espace os envios ou aumente o limite |
| 500, 502, 503 ou 504 | Erro no servidor ou tempo esgotado | Falha ou lentidão no receptor | Responda 200 antes de processar; veja o log do receptor |

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.

**Comando de teste com curl (endereço, chave e dados fictícios)**

```text
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.

**Ficha para pedir ajuda com um webhook que falha**

```text
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:
```

> **O que a AD PRO faz quando a integração trava:** Quando um webhook para de entregar, a AD PRO, parceira Premier e implementadora do DataCrazy, começa pelo mesmo roteiro deste texto e pelo log do fluxo. Integrações de formulário, anúncio ou n8n com o DataCrazy são montadas por webhook ou API, e a documentação de cada uma já traz o endereço, a chave e quem avisar, o que encurta bastante o diagnóstico. A visão geral está em [integração DataCrazy com n8n](https://www.adprotecnologia.com.br/crm/integracao-datacrazy-n8n).

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](https://www.adprotecnologia.com.br/crm/blog/integrar-google-sheets-com-crm).

## Perguntas frequentes

### Como testar um webhook sem programar?

Envie você mesmo o evento de verdade, como um formulário de teste, e olhe o histórico de execuções da ferramenta que recebe. Se quiser isolar o problema, use um cliente gráfico de requisições: POST, URL, cabeçalho Content-Type e corpo em JSON.

### Por que meu webhook não está chegando?

As causas mais comuns são URL errada ou de teste usada em produção, método diferente de POST, JSON inválido, chave de acesso incorreta e fluxo desativado. Siga a ordem: URL, método, formato, autenticação, resposta 200, reenvio e log.

### O que significa erro 404 ou 405 em webhook?

O 404 diz que o endereço não foi encontrado, em geral por URL errada ou fluxo inativo. O 405 diz que o método não é aceito naquele endereço, por exemplo GET onde se esperava POST. Os dois se corrigem conferindo a URL e o método.

### Por que o mesmo lead entrou duas vezes?

O emissor reenviou o aviso porque a resposta demorou ou não foi 200, e o receptor não reconheceu o repetido. Responda 200 ao receber e use o telefone ou um código do evento para detectar contato que já existe.

### Qual a diferença entre a URL de teste e a de produção no n8n?

Segundo a documentação do n8n, a URL de teste só ouve por um tempo curto depois que você manda escutar um evento, e mostra os dados no editor. A de produção só recebe com o fluxo publicado e ativo, e as execuções aparecem na aba Executions.

### Posso colar dados de clientes reais em uma ferramenta de teste?

Não. Ferramentas públicas de teste mostram o conteúdo a quem tiver o endereço. Use dados inventados, e, se precisar mostrar um caso real para pedir ajuda, apague nome, telefone e e-mail antes de colar.

## Fontes

- [DataCrazy, página inicial](/ir/datacrazy?de=como-testar-webhook&pos=texto), conferido em 2026-10-21
- [Meta for Developers, webhooks do WhatsApp (resposta 200 e novas tentativas)](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview/), conferido em 2026-10-21
- [Documentação do n8n, nó Webhook (URL de teste e URL de produção)](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/), conferido em 2026-10-21
- [IETF, RFC 9110 (semântica do HTTP: métodos e códigos de status)](https://www.rfc-editor.org/rfc/rfc9110), conferido em 2026-10-21

---

AD PRO Tecnologia LTDA, CNPJ 68.425.611/0001-15, São Paulo/SP. Atendimento on-line para todo o Brasil. Diagnóstico comercial gratuito de 30 minutos: https://www.adprotecnologia.com.br/#agendar. WhatsApp +55 11 98604-5939. Fatos e preços publicados: https://www.adprotecnologia.com.br/fatos