Um webhook no n8n é uma URL que recebe dados de outro serviço e inicia um workflow automaticamente. Com ele, você pode pegar o envio de um formulário, um pedido de uma loja ou um evento de um sistema e encaminhar as informações para planilhas, bancos de dados, e-mail, WhatsApp ou qualquer outra etapa conectada ao n8n.
O caminho mais simples é criar um Webhook node, escolher o método POST, enviar um JSON de teste e conferir o resultado no editor. Depois, você troca a URL de teste pela URL de produção, publica o workflow e adiciona autenticação antes de divulgar o endereço.
O que você vai montar
O exemplo deste guia recebe os dados de um formulário simples com nome, e-mail e assunto. O fluxo terá três partes:
- Webhook: recebe uma requisição HTTP com os dados do formulário;
- Set ou Edit Fields: organiza os campos e pode criar um valor padrão para o status;
- Respond to Webhook: devolve uma resposta clara para o sistema que enviou os dados.
O Webhook node é um gatilho. Isso significa que ele inicia a execução quando recebe um evento, em vez de ficar sendo chamado por outro nó. A documentação do n8n também descreve o webhook como uma forma de processar dados e devolver um resultado, funcionando de maneira parecida com um endpoint de API.
Webhook, API e formulário: qual é a diferença?
Uma API é um conjunto de regras para dois sistemas conversarem. Um endpoint é um endereço específico dessa API. O webhook é um endpoint que você disponibiliza para receber um evento, normalmente enviado por outro serviço.
Imagine um formulário de orçamento. Quando alguém clica em enviar, o formulário faz uma requisição para a URL do n8n. O Webhook node recebe os campos, o workflow registra o contato e a resposta informa se o envio foi aceito. O usuário não precisa abrir o n8n nem saber o que aconteceu nos bastidores.
Esse modelo é diferente de consultar um sistema a cada minuto para descobrir se há novidades. No webhook, o serviço de origem avisa o n8n quando o evento acontece. Isso costuma reduzir consultas desnecessárias, mas exige que a URL esteja acessível e protegida.
Como criar um webhook no n8n
1. Crie um workflow e adicione o Webhook node
Abra o n8n, crie um workflow e adicione o nó Webhook. No campo HTTP Method, selecione POST, porque vamos enviar os dados no corpo da requisição. No campo Path, use um nome simples, como formulario-contato.
O n8n cria automaticamente um caminho aleatório para evitar conflitos, mas você pode definir um caminho próprio quando precisa de uma URL previsível. Não use dados pessoais, senhas ou chaves no caminho: a URL pode aparecer em logs, históricos e ferramentas de monitoramento.
2. Escolha a resposta inicial
Para começar, no campo Respond, escolha Immediately. Assim, o n8n retorna uma resposta logo que o workflow começa. Essa é a melhor opção para um primeiro teste porque separa o recebimento da requisição do processamento que virá depois.
Quando o sistema que envia os dados precisar receber o resultado de uma etapa posterior, você pode escolher When Last Node Finishes ou Using ‘Respond to Webhook’ Node. A segunda alternativa oferece mais controle sobre corpo, cabeçalhos e código de resposta.
3. Copie a URL de teste
O nó mostra duas URLs: Test URL e Production URL. Durante a construção, use a URL de teste. Clique em Listen for test event ou execute o workflow antes de enviar a requisição. Segundo a documentação do n8n, o webhook de teste fica escutando por 120 segundos.
Não coloque a URL de teste em um formulário usado por clientes. Ela serve para desenvolvimento e os dados recebidos aparecem no editor. Para uso real, o workflow precisa ser publicado e a URL de produção deve ser usada.
Como enviar dados para o webhook
Você pode testar pelo terminal usando o curl. Troque o endereço pelo Test URL copiado do seu nó:
curl -X POST "https://seu-n8n.exemplo/webhook-test/formulario-contato" \
-H "Content-Type: application/json" \
-d '{
"nome": "Ana Souza",
"email": "ana@example.com",
"assunto": "Orçamento"
}'O método POST envia os dados no corpo da requisição. O cabeçalho Content-Type: application/json avisa ao n8n que esse corpo está no formato JSON. Se você enviar um formulário tradicional, o corpo pode chegar como campos de formulário; por isso, confirme no painel de execução como os dados foram interpretados antes de criar as próximas etapas.
Também dá para fazer o mesmo com JavaScript no navegador:
fetch("https://seu-n8n.exemplo/webhook-test/formulario-contato", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
nome: "Ana Souza",
email: "ana@example.com",
assunto: "Orçamento"
})
});O navegador pode bloquear a chamada por causa de CORS se o formulário estiver em outro domínio. Nesse caso, configure Allowed Origins (CORS) no Webhook node com o domínio que realmente fará a chamada. Evite deixar * em produção quando você já sabe de onde virão as requisições.
Como organizar os dados dentro do n8n
Depois do Webhook node, adicione um nó Edit Fields — chamado de Set em versões ou interfaces anteriores — para selecionar os campos que seguirão no fluxo. Você pode mapear expressões como:
{{ $json.body.nome }}para o nome;{{ $json.body.email }}para o e-mail;{{ $json.body.assunto }}para o assunto;novocomo valor fixo para o status.
A estrutura exata pode mudar conforme a forma como o serviço envia os dados. Em uma requisição JSON comum, o conteúdo costuma aparecer dentro de body. Abra a execução recebida e confirme os nomes antes de copiar as expressões. Automatizar no escuro é uma maneira eficiente de criar uma planilha cheia de células vazias.
Como devolver uma resposta útil
Se o sistema de origem só precisa saber que o evento chegou, Immediately já resolve. Para devolver uma mensagem produzida pelo workflow, adicione o nó Respond to Webhook depois das etapas que precisam terminar.
No Webhook node, altere Respond para Using ‘Respond to Webhook’ Node. No novo nó, escolha JSON e informe um corpo como este:
{
"ok": true,
"mensagem": "Contato recebido",
"status": "novo"
}Você também pode ajustar o código HTTP e os cabeçalhos da resposta. Em um fluxo de criação, por exemplo, um código 200 ou 201 pode indicar sucesso, enquanto uma falha de validação pode retornar um código de erro. O importante é que o sistema que chamou o webhook saiba interpretar o resultado.
O Respond to Webhook executa uma vez usando o primeiro item recebido. Se você precisar devolver vários itens, use a opção All Incoming Items ou agregue os dados antes de responder. Não conte com um loop para enviar várias respostas para a mesma requisição.
Como publicar o webhook em produção
- Salve o workflow e confirme se os nós estão conectados.
- Faça um teste usando a Test URL.
- Confira os campos recebidos e corrija as expressões.
- Ative ou publique o workflow.
- Troque a URL de teste pela Production URL no formulário ou serviço de origem.
- Envie um evento real e confira a execução na aba Executions.
A URL de produção não exibe os dados no editor como a URL de teste. Isso não significa que o workflow falhou: as execuções de produção podem ser consultadas na área de execuções. Em uma instalação própria, o endereço também precisa estar acessível pela internet ou por uma rede que consiga alcançar o n8n.
Se você pretende enviar o resultado para uma planilha, o guia do JSMS sobre como registrar dados no Google Sheets com n8n mostra uma aplicação complementar para a etapa de destino.
Como proteger o endpoint
Não trate a URL como segredo suficiente. Ela pode vazar em código do navegador, capturas de tela, históricos e logs. No Webhook node, use pelo menos um método de autenticação:
- Basic auth: exige usuário e senha na chamada;
- Header auth: valida um cabeçalho definido por você;
- JWT auth: usa um token assinado;
- IP Allowlist: limita os endereços que podem chamar o endpoint, quando os IPs são conhecidos.
Para um formulário público, não coloque a senha de autenticação no JavaScript enviado ao navegador. Nesse caso, prefira um backend intermediário, uma solução de formulário que assine as requisições ou uma camada de validação própria. Para um serviço servidor a servidor, Header auth ou JWT costuma ser mais adequado do que expor credenciais no cliente.
Também valide os dados antes de enviar e-mail, gravar informações ou chamar uma API. Confira formato do e-mail, tamanho do texto e campos obrigatórios. O Webhook node oferece a opção Only Run If, que pode impedir a execução quando uma condição do corpo não for atendida, mas ela não substitui a validação completa do fluxo.
Problemas comuns
O webhook retorna 404
Confirme se você está usando a URL de teste enquanto o editor está escutando ou a URL de produção depois de publicar. Confira também se o caminho e o método são os mesmos configurados no nó.
Nada aparece no editor
A URL de teste só fica disponível durante a janela de escuta. Clique novamente em Listen for test event e envie a requisição logo depois. Se você estiver usando a URL de produção, procure a execução na aba Executions.
O workflow não inicia
Veja se ele está publicado, se o endereço do n8n pode ser alcançado pelo serviço de origem e se não há autenticação bloqueando a chamada. Em n8n instalado localmente, localhost só é acessível pelo próprio computador; um serviço externo não consegue chamar esse endereço sem túnel, proxy ou publicação adequada.
O caminho já está em uso
O n8n permite apenas um webhook para cada combinação de caminho e método HTTP. Altere o caminho ou despublique o workflow que está usando a combinação conflitante.
A chamada demora e falha
Não faça o serviço de origem esperar por uma tarefa longa se ele só precisa confirmar o recebimento. Responda imediatamente e processe o restante em segundo plano. Na documentação do n8n Cloud, requisições que não recebem resposta em até 100 segundos podem falhar com o código 524 por causa da camada Cloudflare.
Limites que você precisa conhecer
- O Webhook node aceita métodos HTTP comuns, como GET, POST, PATCH e PUT, mas o método enviado precisa corresponder ao configurado.
- A documentação atual informa limite máximo de payload de 16 MB; em instalação própria, esse limite pode ser ajustado pela variável
N8N_PAYLOAD_SIZE_MAX. - Um webhook público pode receber spam, chamadas repetidas e dados malformados. Use autenticação, validação, limite de tamanho e registro de erros.
- Um POST não é automaticamente idempotente: se o remetente repetir a chamada, o workflow pode criar dois registros. Salve um identificador do evento e faça uma verificação de duplicidade quando isso for importante.
Vale a pena usar webhook no n8n?
Vale a pena quando você precisa conectar um serviço ao n8n e não existe um gatilho pronto. O recurso é simples para receber formulários, notificações, pedidos e eventos de sistemas internos. Ele também ajuda a transformar o n8n em uma ponte entre ferramentas que não conversam diretamente.
O cuidado é não confundir uma URL que recebe dados com uma API completa. Em produção, você ainda precisa pensar em autenticação, validação, duplicidade, tempo de resposta, logs e tratamento de falhas. O webhook abre a porta; a qualidade da automação depende do que você faz depois dela.
Perguntas frequentes
O que é um webhook no n8n?
É uma URL que recebe uma requisição HTTP e usa os dados recebidos para iniciar um workflow. Ele é útil quando o serviço que envia o evento não tem um gatilho pronto no n8n.
Qual é a diferença entre a URL de teste e a URL de produção?
A URL de teste funciona enquanto você seleciona Listen for test event e fica disponível por 120 segundos. A URL de produção funciona depois que o workflow é publicado e as execuções aparecem na aba Executions, não no editor.
Como proteger um webhook do n8n?
Use Basic auth, Header auth ou JWT auth no próprio Webhook node. Dependendo do cenário, também é possível limitar os endereços IP permitidos e validar um campo do corpo antes de continuar o workflow.
Por que meu webhook retorna erro 404 ou não recebe dados?
As causas mais comuns são usar a URL errada, não deixar o webhook de teste escutando, não publicar o workflow de produção, escolher um método HTTP diferente ou repetir um caminho já usado por outro webhook.
Consultado em 25 de agosto de 2026. Os nomes dos campos podem mudar entre versões do n8n; confirme a interface da sua instalação antes de publicar o endpoint.