Webhook no n8n: como criar, testar e colocar no ar

Crie o nó Webhook, escolha autenticação e resposta, teste com curl e entenda a diferença entre Test URL e Production URL antes de publicar o workflow.

Por Redação Eleven Host · @robson.direitodigital · 27 de outubro de 2026 · 7 min de leitura

Um webhook no n8n é um endereço que fica esperando: quando outro sistema envia dados para ele, o workflow começa a rodar. Este guia mostra como criar, testar e colocar o webhook no ar, e como resolver os problemas que aparecem.

Os passos seguem a documentação oficial do n8n sobre o nó Webhook. Os nomes dos campos aparecem em inglês, como na tela, e os endereços de exemplo usam n8n.seudominio.com.br.

O que é um webhook

Sem webhook, o n8n precisaria perguntar de tempos em tempos se algo mudou em outro sistema. Com ele, a lógica se inverte: o outro sistema avisa o n8n quando o evento acontece. O nó Webhook é um nó de gatilho, isto é, é ele que inicia o workflow ao receber os dados.

Alguns exemplos genéricos: o envio de um formulário do site, um pedido novo na loja virtual ou um pagamento aprovado no sistema de pagamento. Em cada caso, o sistema de origem manda uma requisição HTTP para o endereço do webhook, com os dados do evento.

O nó também pode devolver uma resposta a quem chamou, com os dados do fim do workflow, e assim funcionar como um endpoint de API.

Passo a passo: criar o webhook no n8n

1. Crie um workflow novo no n8n.
2. Adicione o nó Webhook como primeiro nó. Ele é um gatilho, então abre o fluxo.
3. Em HTTP Method, escolha POST se o outro sistema vai enviar dados. O nó aceita DELETE, GET, HEAD, PATCH, POST e PUT.
4. Em Path, use o caminho aleatório que o n8n já sugere, que evita conflito entre webhooks, ou defina um próprio. O caminho próprio pode ter parâmetros de rota, como /:variable.
5. Em Authentication, prefira Header auth a None: com ele, a chamada precisa trazer o cabeçalho definido na credencial.
6. Em Respond, escolha como o webhook responde (veja a seção abaixo).
7. Clique em Listen for Test Event. O n8n passa a esperar uma chamada na Test URL.
8. Copie a Test URL que aparece no próprio nó e faça a chamada de teste.
9. Veja os dados chegarem no editor e ligue o próximo nó.

As opções de autenticação

O campo Authentication aceita Basic auth, Header auth, JWT auth (por credenciais do tipo Webhook), n8n User Auth (só para usuários logados na instância) ou None. Com None, o webhook fica sem autenticação. Para dados reais, prefira uma das outras opções.

Como escolher o Respond

O campo Respond define o que o chamador recebe de volta. As opções principais:

• Immediately: o n8n responde logo com a mensagem "Workflow got started". Serve quando o outro sistema só precisa saber que o aviso chegou.
• When Last Node Finishes: devolve a saída do último nó. Serve quando o chamador espera o resultado do workflow.
• Using 'Respond to Webhook' Node: a resposta segue o que você configurar no nó Respond to Webhook.

Há ainda a opção Streaming response, que exige nós com suporte a streaming, como o AI agent.

Prefere começar com o n8n já contratado? Veja os planos a partir de R$ 19,90/mês no n8n Essencial. Conhecer os planos de n8n

Testar o webhook com curl

Com o n8n esperando o evento de teste, rode o comando abaixo no terminal. Copie a URL do próprio nó em vez de montar o endereço à mão: o caminho real é o que aparece lá.

• curl -X POST "https://n8n.seudominio.com.br/webhook-test/meu-caminho" -H "Content-Type: application/json" -d '{"nome":"Maria","pedido":123}'

Se você escolheu Header auth, acrescente ao comando o cabeçalho e o valor definidos na sua credencial, no formato -H "nome-do-cabecalho: valor". Sem isso, a chamada não passa pela autenticação configurada.

Depois do comando, o nó Webhook mostra no editor os dados recebidos, neste exemplo nome e pedido. Com os dados à vista, use o campo que precisa no próximo nó. O teste também funciona com o botão Execute workflow, desde que o workflow não esteja ativo.

Test URL x Production URL

Este ponto pede atenção. O nó tem dois endereços, e cada um é registrado em um momento.

• Test URL: o n8n a registra quando você clica em Listen for Test Event ou em Execute workflow, com o workflow inativo. Quando ela é chamada, os dados aparecem no editor.
• Production URL: o n8n a registra quando você publica (ativa) o workflow. Ela não mostra os dados no editor.

Na prática: monte e teste o fluxo com a Test URL, publique o workflow e troque, no sistema que envia os dados, o endereço de teste pelo de produção. Para conferir o que chegou, abra a aba Executions do workflow.

Problemas comuns

• URL de teste usada em produção. O sistema de origem ficou apontando para o endereço de teste. O n8n registra esse endereço quando está ouvindo o evento de teste. Troque pelo endereço de produção.
• Workflow não ativado. A Production URL só é registrada depois de publicar. Se o workflow estiver inativo, a Production URL não está registrada.
• Erro 404 ou método errado. Confira se o método do nó (por exemplo, POST) é o mesmo que o outro sistema usa, e se o caminho é igual ao do nó, letra por letra. Confira também se o endereço usado (de teste ou de produção) está registrado naquele momento, como descrito na seção Test URL x Production URL.
• Autenticação recusada. O nome do cabeçalho e o valor precisam ser iguais aos da credencial configurada no nó.
• Payload grande. O tamanho máximo é 16 MB. Na instalação própria, dá para mudar esse limite com a variável N8N_PAYLOAD_SIZE_MAX.
• URL com localhost na instalação própria. Atrás de um proxy reverso, o n8n precisa saber o endereço público. A partir da versão 2.35.0, a variável é N8N_WEBHOOK_URL; nas versões anteriores, WEBHOOK_URL, que gera aviso de depreciação a partir da 2.35.0. Exemplo: N8N_WEBHOOK_URL=https://n8n.seudominio.com.br/. Sem essa variável, o n8n monta o endereço a partir de N8N_PROTOCOL, N8N_HOST e N8N_PORT, o que não funciona atrás de proxy, porque internamente o n8n roda na porta 5678.

Se você ainda vai instalar o n8n por conta própria, o guia Instalar n8n na VPS: passo a passo com Docker mostra a instalação com Docker, e este artigo cuida do webhook. Para o endereço público, o guia Apontar domínio para VPS: passo a passo com registro A explica o apontamento do domínio.

Segurança do webhook

O webhook recebe chamadas de outros sistemas. Três cuidados ajudam a protegê-lo:

• Autenticação. Use Header auth, Basic auth ou JWT auth em vez de None.
• IP(s) Allowlist. Nas opções do nó, você pode listar os IPs que podem chamar o webhook, quando o sistema de origem tem endereço conhecido.
• Resposta enxuta. Não devolva dados sensíveis na resposta. Com When Last Node Finishes, a saída do último nó vai para quem chamou.

Na instalação própria, o Firewall para VPS: como proteger seu servidor ajuda a deixar abertas só as portas de que o servidor precisa.

Procurando um plano de n8n? Conheça os planos, do n8n Essencial a partir de R$ 19,90/mês. Ver planos de n8n

Perguntas frequentes

Por que o webhook funciona no teste e não em produção?

Duas causas possíveis são o workflow ainda não estar publicado e o sistema de origem continuar apontando para a Test URL. A Production URL só é registrada ao publicar o workflow.

Onde vejo os dados que chegam pela Production URL?

Na aba Executions do workflow. A Production URL não mostra os dados no editor, ao contrário da Test URL.

Qual método HTTP escolher no nó Webhook?

Use POST quando o outro sistema envia dados no corpo da requisição. O nó também aceita DELETE, GET, HEAD, PATCH e PUT; o método escolhido precisa ser o mesmo que o sistema de origem usa.

Preciso de autenticação no webhook?

Para dados reais, é o recomendado. O campo aceita Basic auth, Header auth, JWT auth e n8n User Auth. A opção None deixa o endereço aberto a quem o conhecer.

Qual o tamanho máximo do que o webhook recebe?

16 MB por padrão. Na instalação própria do n8n, esse limite pode ser alterado com a variável N8N_PAYLOAD_SIZE_MAX.