Como criar um webhook no n8n para receber dados de um formulário

Um webhook é o caminho mais direto para fazer outro serviço avisar o n8n que algo aconteceu. Em vez de consultar uma API de tempos em tempos, você cria uma URL, recebe uma requisição HTTP e deixa o fluxo continuar com os dados enviados.

Neste tutorial, você vai criar um endpoint para receber um cadastro de formulário, testar a chamada com cURL e devolver uma resposta JSON. O exemplo serve para leads, pedidos, alertas e integrações próprias — sem precisar escrever um servidor do zero.

O que é um webhook no n8n?

Webhook é uma URL que espera uma requisição de outro sistema. Quando um visitante envia um formulário, quando um pagamento muda de status ou quando uma ferramenta registra um evento, o serviço envia os dados para essa URL. O n8n recebe o pacote e inicia o workflow.

A diferença para o polling é simples: no polling, seu sistema pergunta “aconteceu algo novo?” repetidamente. No webhook, o sistema de origem avisa quando há novidade. Isso costuma reduzir chamadas desnecessárias e diminuir o intervalo entre o evento e a automação.

O nó Webhook aceita métodos HTTP como POST, GET, PUT e PATCH, além de permitir parâmetros no caminho. Para receber um formulário em JSON, usaremos POST: o conteúdo enviado fica disponível no objeto de entrada, incluindo body, headers, params e query.

O que você precisa antes de começar

• uma conta no n8n Cloud ou uma instalação auto-hospedada acessível;
• permissão para criar e publicar workflows;
• um cliente HTTP para testar, como cURL, Postman ou Insomnia;
• um serviço capaz de enviar uma requisição HTTP para a URL, como seu formulário ou aplicação.

Se o n8n estiver rodando apenas em localhost, um serviço externo não conseguirá alcançá-lo diretamente. Para um teste local, a documentação do n8n orienta usar o modo de túnel; em produção, prefira uma instalação publicada atrás de HTTPS e um domínio controlado por você.

Como criar o webhook no n8n

1. Crie o workflow e adicione o nó Webhook

Abra o n8n, crie um workflow novo e adicione o gatilho Webhook. Configure os campos assim:

Campo	Valor do exemplo	Por que usar
HTTP Method	POST	Recebe dados no corpo da requisição
Path	novo-lead	Cria uma URL fácil de identificar
Authentication	Header Auth	Exige um segredo no cabeçalho
Respond	When Last Node Finishes	Devolve o resultado produzido pelo fluxo
Response Data	First Entry JSON	Retorna um objeto JSON, em vez de uma lista

O endereço será parecido com https://seu-n8n.com/webhook/novo-lead. Não copie esse exemplo literalmente: o domínio e o caminho dependem da sua instalação.

2. Proteja a URL com Header Auth

No campo de autenticação, crie uma credencial de cabeçalho. Um exemplo é usar o nome X-Webhook-Secret e um valor longo, aleatório e exclusivo para essa integração. O remetente deverá enviar o mesmo cabeçalho em todas as chamadas.

O n8n também documenta Basic Auth e JWT como opções. A escolha depende do serviço que fará a chamada, mas deixar a autenticação em None não é uma boa ideia para um endpoint que recebe dados de clientes, pedidos ou sistemas internos.

3. Prepare a resposta do workflow

Conecte um nó Edit Fields (Set) ao Webhook. Crie, por exemplo, estes campos:

• ok: valor booleano true;
• mensagem: texto Lead recebido;
• nome: expressão {{$json.body.nome}};
• email: expressão {{$json.body.email}}.

Se você ativar Keep Only Set, a resposta fica limitada aos campos criados no Edit Fields. Isso ajuda a não devolver, sem querer, cabeçalhos, parâmetros ou outros dados recebidos.

Como testar o webhook com cURL

No nó Webhook, clique em Listen for Test Event ou execute o workflow para registrar a URL de teste. Em seguida, abra um terminal e envie uma requisição como esta:

curl -X POST "COLE_AQUI_A_URL_DE_TESTE" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: TROQUE_ESTE_VALOR" \
  -d '{
    "nome": "Ana Souza",
    "email": "ana@example.com",
    "origem": "formulario-do-site"
  }'

Troque a URL e o segredo pelos valores do seu workflow. Se tudo estiver certo, o n8n mostrará a execução no editor e a resposta deverá conter ok, mensagem, nome e email.

A URL de teste fica disponível por 120 segundos depois que você começa a escutá-la. Se o comando for executado depois disso, ative novamente o listener. Essa janela curta é intencional: ela evita que o endpoint de desenvolvimento fique aberto indefinidamente.

Quando trocar para a URL de produção

O n8n fornece duas URLs para o nó: uma de teste e outra de produção. A URL de teste serve para depurar e exibir os dados no editor. Quando o workflow estiver pronto, publique-o e use a URL de produção; ela executa o fluxo, mas não mostra a entrada diretamente no editor. As execuções continuam disponíveis na área de execuções do n8n.

O erro clássico aqui é copiar a URL de teste para o formulário e depois fechar o editor. O formulário para de funcionar e parece que a automação quebrou. O fluxo correto é:

1. testar com a URL de teste;
2. confirmar os campos recebidos e a resposta;
3. publicar o workflow;
4. substituir a URL no formulário pela URL de produção;
5. fazer uma chamada real e verificar a execução.

Se a sua automação também precisa responder mensagens, vale ver o exemplo do JSMS sobre como criar um bot no Telegram com n8n. A lógica é parecida: um evento inicia o fluxo, mas o canal e o formato da resposta mudam.

Erros comuns e como corrigir

Erro 404 ou “webhook not found”

Confira se você está usando a URL correta. No teste, o listener precisa estar ativo; na produção, o workflow precisa estar publicado. Também verifique se o caminho não foi alterado depois que você copiou o endereço.

Erro 405 ou método não permitido

O método da chamada precisa ser o mesmo configurado no nó. Se o Webhook está em POST e o cliente envia GET, o n8n não tratará a requisição como você espera.

Erro 401 ou 403

O nome ou o valor do cabeçalho não corresponde à credencial criada no n8n. Compare as duas pontas sem colocar o segredo na URL. Se houver proxy reverso ou lista de IPs permitidos, confira essa camada também.

O corpo chega vazio

Envie o cabeçalho Content-Type: application/json e um JSON válido. No n8n, os dados normalmente ficam em $json.body; assim, o campo email do exemplo pode ser acessado com {{$json.body.email}}.

O n8n informa que o caminho já está em uso

O n8n não permite registrar mais de um webhook com a mesma combinação de caminho e método HTTP. Despublique o workflow conflitante ou escolha outro path, como novo-lead-v2.

Cuidados antes de colocar em produção

• Use autenticação: um caminho difícil de adivinhar não substitui um segredo no cabeçalho.
• Valide os dados: verifique campos obrigatórios, tamanho de texto e formato de e-mail antes de gravar ou encaminhar o conteúdo.
• Evite respostas exageradas: devolva apenas o que o sistema de origem precisa saber.
• Planeje reenvios: alguns serviços repetem a chamada quando não recebem uma resposta rápida. Use um identificador do evento para não criar dois pedidos ou dois leads.
• Restrinja o CORS quando necessário: se o navegador chamar o endpoint diretamente, configure as origens permitidas em vez de deixar qualquer origem acessar a URL.
• Monitore as execuções: uma resposta HTTP bem-sucedida não garante que a etapa posterior, como salvar no CRM, terminou corretamente.

Vale a pena usar webhook no n8n?

Sim, quando o sistema de origem já consegue enviar eventos por HTTP. O Webhook é uma porta de entrada flexível para ligar formulários, e-commerces, APIs próprias, sistemas legados e serviços que não têm uma integração pronta com o n8n.

Ele não resolve tudo sozinho. Você ainda precisa cuidar de autenticação, validação, reenvio e observabilidade. Mas, para uma primeira automação, o fluxo é enxuto: receber o evento, transformar os campos e chamar o próximo serviço. É justamente aí que o n8n é mais útil — não por fazer mágica, mas por tirar o trabalho repetitivo do caminho.

Perguntas frequentes

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

A URL de teste fica ativa enquanto você escuta um evento e mostra os dados no editor. A URL de produção funciona depois que o workflow é publicado e permite acompanhar a execução pela área de execuções.

Posso chamar um webhook do n8n pelo navegador?

Sim, mas uma chamada feita pelo navegador pode exigir configuração de CORS. Para enviar dados estruturados, um formulário ou aplicação normalmente usa uma requisição POST com JSON.

Preciso usar autenticação no webhook?

Para um endpoint público que recebe dados reais, é recomendável usar autenticação. O nó Webhook oferece Header Auth, Basic Auth e JWT, entre outras configurações documentadas pelo n8n.

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

As causas mais comuns são o uso da URL de teste depois que o listener expirou, o workflow não publicado, o método HTTP diferente ou uma credencial de cabeçalho incorreta.