Webhook de teste ou de produção: por que o seu retorna 404
As quatro causas do 404 em webhook do n8n, ordenadas por frequência, e o hábito de três passos que evita o problema na entrega.
Resumo por IA
Resumo gerado por IA, revisado pela redação.
Se o seu webhook devolve 404, a causa mais provável é estar chamando a URL de teste quando deveria chamar a de produção. São endereços diferentes, com regras diferentes de ativação: a de teste só funciona enquanto você está ouvindo na tela; a de produção só existe depois que o fluxo é publicado. Entender essa distinção resolve o erro mais frequente de quem coloca o primeiro webhook no ar.
Adicione ao Google NotíciasAs duas URLs
O node Webhook mostra as duas, e você alterna entre elas na própria tela.
URL de teste
O n8n registra o webhook de teste quando você seleciona Listen for Test Event ou executa o fluxo, com o fluxo não ativo. Ao chamar a URL, os dados aparecem na tela do fluxo, o que é ótimo para construir e conferir o formato do que chega.
A limitação: ela funciona enquanto você está ouvindo. Saiu da tela, o registro cai, e as chamadas seguintes devolvem 404.
URL de produção
O n8n registra o webhook de produção quando o fluxo é publicado. Ao usá-la, os dados não aparecem na tela do fluxo — o que assusta quem espera ver algo acontecendo e conclui que não funcionou.
Mas os dados estão gravados: basta abrir a aba de execuções do fluxo e selecionar a execução que quer ver.
| Teste | Produção | |
|---|---|---|
| Quando é registrada | Ao ouvir ou executar, com fluxo inativo | Ao publicar o fluxo |
| Mostra dados na tela | Sim | Não |
| Onde ver o que chegou | No próprio fluxo | Na aba de execuções |
| Funciona sozinha | Não | Sim |
| Serve para | Construir | Rodar de verdade |
Diagnóstico do 404
Percorra nesta ordem — está ordenado por frequência:
1. Você copiou a URL de teste para o sistema externo
É a causa campeã. Você montou, testou, funcionou, colou a URL no outro sistema e foi embora. No dia seguinte, 404 em tudo.
Como reconhecer: o endereço contém um trecho indicando teste. Volte ao node, alterne para a URL de produção e atualize no sistema externo.
2. O fluxo não está publicado
A URL de produção só passa a existir depois que o fluxo é publicado. Fluxo salvo mas não publicado não tem endereço de produção ativo.
3. O método não bate
O node está configurado para POST e quem chama usa GET. O endereço existe, o verbo não — e a resposta pode ser 404 em vez de algo mais claro.
Se você precisa aceitar os dois, ative a opção de permitir múltiplos métodos nas configurações do node.
4. O caminho está diferente
Uma barra a mais no fim, um caractere trocado, um pedaço faltando. Copie e cole do node em vez de digitar.
Quando não é 404
Deu 401 ou 403. O endereço está certo e a autenticação do node está barrando. Confira o que o sistema externo envia contra o que o node exige.
Respondeu 200 mas nada aconteceu. O webhook recebeu, o fluxo rodou e quebrou depois. Abra a aba de execuções e procure o primeiro node vermelho.
Funciona no teste e falha em produção. Duas causas típicas: alguma expressão depende de dado que só existia no teste manual, ou o fluxo usa o node Code e a instância roda em modo de fila sem executor configurado em cada trabalhador.
Existe um caso conhecido que confunde muito: fluxos ativados pela API em vez da interface podem não registrar o caminho do webhook. O fluxo aparece como ativo, e o endereço devolve 404 mesmo assim. Se você automatiza a ativação, teste o endereço depois — não confie no indicador de ativo.
O hábito que evita o problema
Ao terminar de construir, faça sempre estes três passos, nesta ordem:
Publique o fluxo.
Copie a URL de produção, não a que estava aberta na tela.
Dispare uma vez pelo sistema externo real e confirme na aba de execuções.
O terceiro passo é o que separa quem descobre o problema agora de quem descobre pelo cliente na segunda-feira.
404 quase sempre é URL de teste em produção. Publique, copie a URL de produção e confirme pela aba de execuções — a ausência de dado na tela é esperada.
Perguntas frequentes
Por que meu webhook do n8n retorna 404?
Na maioria das vezes porque está sendo usada a URL de teste, que só funciona enquanto você está ouvindo na tela com o fluxo inativo. Outras causas comuns são o fluxo não estar publicado, o método HTTP não corresponder ao configurado e diferença no caminho.
Qual a diferença entre URL de teste e de produção?
A de teste é registrada quando você manda ouvir um evento ou executa o fluxo inativo, e mostra os dados na tela. A de produção é registrada ao publicar o fluxo, funciona continuamente e não exibe os dados no editor — eles ficam disponíveis na aba de execuções.
Meu webhook responde mas não vejo os dados. É erro?
Não. Em produção, o n8n não exibe os dados no editor por design. Para conferir o que chegou, abra a aba de execuções do fluxo e selecione a execução desejada.
Ativei o fluxo pela API e o webhook continua dando 404. O que houve?
Existe um comportamento conhecido em que a ativação feita pela API não registra o caminho do webhook, ao contrário da ativação pela interface. O fluxo aparece ativo e o endereço não responde. Nesse caso, ative pela interface ou teste o endereço antes de considerar concluído.
Funciona no teste e falha em produção. Por quê?
As causas mais frequentes são expressões que dependiam de dados presentes apenas na execução manual e, em instâncias que rodam em modo de fila, a ausência de executor de código configurado em cada trabalhador — o que faz o node Code falhar apenas nas execuções automáticas.
Este tutorial faz parte do guia Curso de n8n do zero ao avançado: o guia completo em português. Veja também: Node, trigger e workflow: o vocabulário do n8n em 10 minutos · A estrutura de dados do n8n: por que tudo é um array com json · Item linking no n8n: como ele decide qual item vai pra saída · Execuções passo a passo: como achar onde o fluxo do n8n quebrou · A Canvas UI do n8n 2.0: o que mudou e como se orientar · n8n Cloud ou self-hosted: a decisão que define seu custo e sua liberdade
