Um webhook no n8n é uma URL que recebe uma requisição HTTP e inicia um workflow. Ele serve para fazer um formulário, loja, sistema interno ou outro aplicativo avisar o n8n assim que um evento acontece, sem precisar ficar consultando a origem de tempos em tempos.
Neste tutorial, você vai montar um fluxo simples: enviar um cadastro em JSON, receber os dados no n8n, conferir o conteúdo e devolver uma resposta HTTP. O exemplo não depende de um aplicativo específico e pode ser adaptado para atendimento, leads, pedidos ou alertas.
O que é um webhook no n8n?
Webhook é um endereço que espera uma chamada HTTP. Quando um serviço envia um evento para esse endereço, o n8n transforma a requisição em entrada do workflow e executa os nós seguintes. É a diferença entre receber uma notificação e perguntar repetidamente se há novidade.
Na prática, você pode usar o mesmo padrão para receber um formulário de orçamento, uma atualização de pagamento, uma mensagem de um sistema legado ou um evento de um site. O n8n também pode devolver o resultado do processamento, funcionando como uma pequena API.
Antes de começar
- Tenha uma instância do n8n Cloud ou uma instalação própria acessível pelo serviço que fará a chamada.
- Separe um caminho para o endpoint, como
lead-site. O caminho deve ser fácil de reconhecer, mas não deve conter senha, token ou dado pessoal. - Tenha o cURL instalado para testar pelo terminal. No Windows, o comando costuma estar disponível no PowerShell e no Prompt de Comando.
Como criar o webhook no n8n
1. Adicione o nó Webhook
Crie um workflow novo, adicione o nó Webhook e escolha POST em HTTP Method. No campo Path, informe algo como lead-site. O POST é adequado para este exemplo porque os dados serão enviados no corpo da requisição.
O n8n mostra duas URLs no nó: Test URL e Production URL. Use a primeira durante a montagem. Para que ela fique escutando, selecione Listen for Test Event ou execute o workflow, conforme a tela da sua versão.
2. Envie um evento de teste
Com a URL de teste copiada, rode um comando como este. Troque URL_DE_TESTE pelo endereço mostrado no seu nó:
curl -X POST "URL_DE_TESTE" \
-H "Content-Type: application/json" \
-d '{"nome":"Ana","email":"ana@example.com","origem":"site"}'Se o teste funcionar, abra os dados recebidos na execução do Webhook. Confirme se os campos chegaram como você esperava antes de conectar e-mails, planilhas ou sistemas externos. Em muitas configurações, o JSON enviado aparece dentro de $json.body; use o painel de saída da sua própria execução como fonte de verdade, porque a estrutura pode variar conforme o tipo de chamada.
3. Valide os campos antes de agir
Depois do Webhook, adicione um nó Edit Fields (Set) ou um nó de código para selecionar os campos necessários. Por exemplo, você pode manter apenas nome, e-mail e origem. Em seguida, use um IF para verificar se o e-mail existe antes de criar um contato ou disparar uma notificação.
Essa etapa parece burocrática até o primeiro sistema externo enviar um campo vazio. Validar antes de agir evita criar registros quebrados e impede que uma entrada inesperada percorra o resto da automação.
Como devolver uma resposta ao sistema
No nó Webhook, a opção Respond define como o n8n responde à chamada. Respond Immediately devolve rapidamente uma confirmação de que o workflow começou. When Last Node Finishes espera o final e pode retornar a saída do último nó.
Se a aplicação precisa de uma resposta específica, escolha Using ‘Respond to Webhook’ Node e adicione o nó Respond to Webhook depois da validação. Nele, escolha o corpo da resposta e o código HTTP. Um retorno simples pode ser:
{
"ok": true,
"mensagem": "Lead recebido"
}Use a opção de resposta imediata quando o processamento for demorado e o sistema de origem só precisar de um recebimento rápido. Use o nó de resposta quando for importante devolver uma decisão, um identificador ou uma mensagem de erro controlada.
Como testar e publicar a URL correta
A URL de teste é para desenvolvimento e só funciona enquanto o n8n está ouvindo o evento. Quando o fluxo estiver pronto, publique o workflow e passe a usar a Production URL no serviço externo. A execução de produção não aparece no editor como a de teste; para acompanhar o que aconteceu, consulte a área de execuções do workflow.
Faça pelo menos três testes antes de trocar o endereço no sistema real:
- uma requisição válida, com todos os campos;
- uma requisição incompleta, para confirmar a validação;
- uma chamada repetida, para observar se o fluxo cria duplicatas.
Cuidados de segurança
Um endpoint sem autenticação pode ser chamado por qualquer pessoa que descubra a URL. No nó Webhook, prefira Header auth, Basic auth ou JWT auth quando o serviço de origem suportar esse método. A opção None faz sentido para um teste controlado, não como padrão de um endpoint que altera dados.
Também valide tipo e tamanho dos campos, não aceite comandos recebidos diretamente no fluxo e evite registrar tokens no histórico. Se precisar guardar chaves usadas por outros nós, use credenciais do n8n ou variáveis de ambiente; o guia do JSMS sobre variáveis de ambiente no Node.js explica a lógica de separar configuração e código.
A documentação atual do n8n informa limite padrão de payload de 16 MB para o Webhook e permite alterar esse limite em instalações próprias com a variável N8N_PAYLOAD_SIZE_MAX. Isso não é convite para enviar arquivos enormes: para mídia e documentos, costuma ser melhor guardar o arquivo em um serviço próprio e mandar ao webhook apenas o identificador.
Erros comuns e como corrigir
“404 Not Found”
Confira se você está usando a URL de teste enquanto o nó está ouvindo ou a URL de produção depois que o workflow foi publicado. Também confirme o método HTTP e o caminho configurados no nó.
O workflow não recebe nada
Veja se o serviço externo realmente fez uma chamada POST, se a URL está acessível pela internet e se a autenticação enviada coincide com a configurada no n8n. Um n8n instalado apenas em localhost não pode ser chamado diretamente por um serviço remoto.
A resposta demora ou chega vazia
Revise a opção Respond e a posição do nó Respond to Webhook. Se o fluxo termina antes desse nó, ou se você escolheu responder apenas no final para um processamento longo, o sistema de origem pode atingir o tempo limite.
Vale a pena usar webhook no n8n?
Sim, quando o sistema que gera o evento oferece webhooks e você precisa reagir sem atraso de uma rotina agendada. O ganho não está em “usar IA” ou em adicionar dezenas de nós: está em conectar uma entrada clara a uma ação verificável.
Para começar, mantenha o primeiro fluxo pequeno: receber, validar, registrar e responder. Depois de confirmar que os eventos são confiáveis, você pode acrescentar notificações, filtros e integrações. A própria documentação do nó Webhook do n8n detalha URLs de teste e produção, autenticação, métodos HTTP e formas de resposta.
Perguntas frequentes
Preciso saber programar para criar um webhook no n8n?
Não. A configuração básica é feita pela interface. Conhecer HTTP, JSON e autenticação ajuda a diagnosticar erros e a criar fluxos mais seguros, mas o primeiro teste pode ser feito sem escrever um aplicativo.
Qual é a diferença entre URL de teste e URL de produção?
A URL de teste é usada enquanto o workflow está ouvindo no editor. A URL de produção é registrada quando o workflow é publicado e deve ser usada pelo serviço real.
Quando devo usar o Respond to Webhook?
Use esse nó quando você precisa controlar o corpo ou o código da resposta depois que outros nós terminarem o processamento. Para apenas confirmar o recebimento, a resposta imediata costuma ser mais simples.
Fontes e documentação
- Documentação oficial do Webhook no n8n.
- Documentação oficial do Respond to Webhook.
- Guia independente sobre webhooks orientados a eventos, consultado em 26 de agosto de 2026.