Webhook no n8n: como receber dados de formulários e sistemas

Comente! ,

Tempo de leitura: 4 minutos

O webhook no n8n é a porta de entrada da maioria das automações: um formulário do site, uma venda na loja virtual ou um pagamento aprovado mandam os dados para uma URL, e o fluxo começa a trabalhar na hora. Neste guia você vai aprender a criar esse gatilho, testar, proteger e evitar os erros que mais aparecem. Para rodar isso em produção com HTTPS pronto, o Cloud VPS n8n da Rubfy já entrega o ambiente configurado.

O que é um webhook

Webhook é uma chamada HTTP que um sistema faz para avisar outro de que algo aconteceu. Em vez de o n8n ficar perguntando de minuto em minuto se chegou pedido novo, a própria loja avisa no momento da venda. É mais rápido e gasta menos recurso dos dois lados.

Se você ainda está começando com a ferramenta, o nosso guia do que é o n8n explica os conceitos de nó, fluxo e execução.

Como criar um webhook no n8n

  1. crie um fluxo novo e adicione o nó Webhook;
  2. escolha o método HTTP. Para receber dados de formulário e de sistemas, o mais comum é POST;
  3. defina um Path fácil de reconhecer, por exemplo novo-lead;
  4. copie a URL e cole no sistema que vai enviar os dados.

O nó mostra duas URLs, e confundir as duas é a causa número um de automação que não dispara.

URL de teste e URL de produção

  • Test URL (contém /webhook-test/): só responde enquanto você clica em Listen for test event no editor, e para depois da primeira chamada. Serve para ver o formato dos dados.
  • Production URL (contém /webhook/): funciona o tempo todo, mas somente com o fluxo ativado no botão do canto superior.

Use a de teste para montar o fluxo e troque pela de produção no sistema de origem antes de ativar.

Testando o webhook no n8n sem esperar um formulário

Não precisa esperar um formulário real para testar. Com a URL de teste escutando, envie esta requisição pelo Postman, pelo Insomnia ou por outro fluxo do próprio n8n com o nó HTTP Request:

POST /webhook-test/novo-lead
Host: automacao.seudominio.com.br
Content-Type: application/json

{"nome": "Maria", "email": "[email protected]", "origem": "site"}

Os campos chegam dentro de body, então no próximo nó você usa expressões como {{ $json.body.email }}.

Responder na hora ou depois de processar

No campo Respond do nó Webhook existem três comportamentos principais:

  • Immediately: devolve 200 na hora e o fluxo segue em segundo plano. Ideal quando quem chama não espera resposta, como a maioria dos formulários.
  • When Last Node Finishes: devolve o resultado do último nó. Útil para fluxos curtos.
  • Using Respond to Webhook Node: você decide o ponto exato e o conteúdo da resposta. É o mais flexível para montar pequenas APIs.

Se o fluxo demora (chama uma IA, por exemplo), prefira responder imediatamente: muitos sistemas cancelam a chamada depois de 10 a 30 segundos e tentam de novo, o que gera execução duplicada. O artigo sobre n8n com inteligência artificial mostra fluxos desse tipo.

Como proteger o endpoint

Uma URL de webhook exposta pode ser chamada por qualquer pessoa que descobrir o endereço. Três camadas simples resolvem:

  • Autenticação no próprio nó: em Authentication, use Header Auth com um token secreto que só o sistema de origem conhece.
  • Path difícil de adivinhar: troque novo-lead por algo com um trecho aleatório.
  • HTTPS obrigatório: além de proteger os dados, vários serviços recusam webhook sem certificado válido. Veja como emitir SSL grátis com Certbot.

Erros comuns e como resolver

  • 404 webhook is not registered: o fluxo não está ativo, ou o sistema está chamando a URL de teste.
  • O fluxo roda duas vezes: o sistema de origem reenviou por não receber resposta a tempo. Responda imediatamente.
  • Dados vazios: o sistema envia como formulário (application/x-www-form-urlencoded) e não JSON. Os campos continuam em body, mas confira os nomes na execução.
  • URL com localhost: o n8n gera a URL a partir da variável WEBHOOK_URL. Se ela não estiver configurada, o endereço sai errado quando há um proxy reverso Nginx na frente.

A documentação oficial do nó Webhook do n8n tem a lista completa de opções.

Rode seus fluxos no Cloud VPS n8n

Webhook precisa de servidor sempre ligado e com HTTPS. No Cloud VPS n8n da Rubfy o n8n já vem instalado em Docker com Nginx e HTTPS configurados, Ubuntu 22.04 LTS, acesso root, workflows e execuções ilimitados, tráfego ilimitado e IP dedicado em datacenter no Brasil, a partir de R$ 69 por mês. É só apontar o domínio e começar a receber os dados.

Artigos relacionados