Um webhook no n8n é um endereço que recebe uma requisição HTTP e inicia um fluxo automaticamente. Neste guia, você vai criar um endpoint para receber os dados de um formulário, testar o envio com cURL e entender a diferença entre a URL de teste e a de produção.
A ideia é simples: em vez de o n8n ficar perguntando a outro serviço se há novidades, o serviço envia os dados assim que algo acontece. Esse modelo serve para formulários, sistemas de pagamento, CRMs, sites próprios e integrações que não têm um nó pronto no n8n.
A tela do n8n separa a URL usada durante o desenvolvimento da URL que deve receber eventos depois que o fluxo for publicado.
O que você precisa antes de começar
- uma instalação do n8n acessível pelo navegador;
- um workflow novo ou já existente;
- um serviço que possa enviar uma requisição HTTP ou o cURL instalado no computador;
- uma ideia clara do formato dos dados que o formulário vai enviar.
Se o n8n estiver rodando apenas em localhost, um serviço externo não conseguirá chamar o webhook diretamente. Para testar de fora da sua rede, você precisará publicar o n8n em um endereço acessível ou usar um túnel apropriado. Não trate um endereço de teste temporário como solução de produção.
Como criar o webhook no n8n
1. Adicione o nó Webhook
Abra um workflow, clique em Add first step e pesquise por Webhook. Esse nó é o gatilho do fluxo: a execução começa quando chega uma requisição no endereço criado por ele.
2. Escolha o método HTTP
Para receber os campos de um formulário, selecione POST. Esse método é adequado quando os dados vão no corpo da requisição. O n8n também documenta suporte a GET, HEAD, PUT, PATCH e DELETE, mas o serviço que envia os dados precisa usar o mesmo método configurado no nó.
3. Defina um caminho fácil de reconhecer
No campo Path, use algo como formulario-contato. O caminho precisa ser único dentro da instalação para não disputar o mesmo endpoint com outro nó Webhook. Evite colocar e-mail, CPF, token ou qualquer dado pessoal no caminho da URL.
4. Escolha a resposta inicial
Para um primeiro teste, deixe o webhook responder imediatamente. Assim, o serviço que enviou os dados recebe uma confirmação sem precisar esperar todo o workflow terminar. Quando a integração exigir uma resposta calculada pelo fluxo, você pode usar o nó Respond to Webhook e devolver um status ou um JSON específico.
Como testar a URL do webhook
O n8n cria duas URLs: Test URL e Production URL. Durante a montagem do fluxo, use a URL de teste. Clique em Listen for test event ou execute o workflow antes de enviar a requisição; a documentação informa que o webhook de teste fica registrado por 120 segundos.
Com o nó ouvindo, abra um terminal e troque o endereço abaixo pela sua Test URL:
curl -X POST 'https://seu-n8n.exemplo/webhook-test/formulario-contato' \
-H 'Content-Type: application/json' \
-d '{"nome":"Ana","email":"ana@exemplo.com","mensagem":"Quero saber mais"}'Se tudo estiver certo, o n8n mostrará uma nova execução no editor. Abra o nó Webhook e confira se os campos aparecem no JSON recebido. A partir daí, você pode ligar nós como Google Sheets, Notion, e-mail, Slack ou um CRM.
Como acessar os dados recebidos no próximo nó
Os campos do corpo ficam disponíveis nos dados de entrada do item. Em expressões do n8n, uma referência típica é:
{{ $json.nome }}
{{ $json.email }}
{{ $json.mensagem }}Se o formulário enviar os dados aninhados, como {"lead":{"nome":"Ana"}}, a expressão muda para {{ $json.lead.nome }}. O melhor jeito de evitar erro é fazer um disparo de teste e escolher o campo pelo painel de expressões, em vez de digitar caminhos longos de memória.
Como publicar o webhook em produção
Depois de testar, publique ou ative o workflow e copie a Production URL. É esse endereço que deve ser cadastrado no formulário ou no sistema externo. A URL de teste é para depuração e não deve ficar gravada na integração definitiva.
Faça um segundo envio usando a URL de produção e confirme a execução na área de execuções do n8n. O editor não exibe esse evento da mesma maneira que exibe um teste, então procure a execução registrada para conferir o payload.
Um exemplo de chamada para produção seria:
curl -X POST 'https://seu-n8n.exemplo/webhook/formulario-contato' \
-H 'Content-Type: application/json' \
-d '{"nome":"Carlos","email":"carlos@exemplo.com","mensagem":"Preciso de um orçamento"}'Como proteger o endpoint
Um webhook público pode ser chamado por qualquer pessoa que descubra o endereço. Para reduzir abuso, use autenticação quando o serviço que envia os dados permitir. O nó Webhook oferece opções como Basic Auth, Header Auth e JWT, além da opção sem autenticação.
Também vale validar o conteúdo antes de gravar ou encaminhar os dados. Confira se os campos obrigatórios existem, limite tamanhos, rejeite formatos inesperados e evite executar comandos com valores que vieram diretamente do formulário. Para operações sensíveis, inclua uma assinatura ou um token secreto enviado em um cabeçalho.
Se o formulário não oferece autenticação, você ainda pode colocar uma validação no início do fluxo e descartar requisições sem um campo secreto. Isso não substitui uma estratégia completa contra abuso, mas evita que qualquer chamada incompleta avance para o CRM ou para uma planilha.
Erros comuns e como corrigir
O webhook não recebe nada
Verifique se você clicou em Listen for test event antes do disparo e se está usando a URL de teste correta. Confira também o método HTTP: um nó configurado para POST não deve ser chamado com GET por engano.
A URL de teste parou de funcionar
Isso pode acontecer porque o registro de teste é temporário. Reative a escuta e envie a requisição novamente. Para uso contínuo, ative o workflow e troque a integração pela Production URL.
O serviço recebe uma resposta, mas o fluxo falha
Veja o histórico da execução e identifique o primeiro nó que apresentou erro. O Webhook pode ter recebido o payload corretamente; o problema pode estar em uma credencial expirada, em um campo com nome diferente ou no formato exigido pelo próximo serviço.
O n8n recebe o pedido, mas os campos ficam vazios
Confirme o cabeçalho Content-Type e o formato do corpo. No exemplo deste artigo, o corpo é JSON. Se o formulário enviar dados como formulário HTML ou parâmetros na URL, os campos podem aparecer em outra seção do item de entrada.
Webhook ou consulta periódica: qual escolher?
O webhook é melhor quando o serviço externo consegue avisar o n8n no momento do evento. A automação tende a reagir mais rápido e não precisa fazer consultas repetidas. Já a consulta periódica, também chamada de polling, pode ser a única alternativa quando a API não oferece webhook.
Na prática, o webhook não elimina todos os problemas: você precisa cuidar de autenticação, duplicidade e falhas de rede. Se o remetente repetir a mesma entrega, pense em uma chave única para não cadastrar o mesmo lead duas vezes. Para integrações importantes, registre o evento recebido antes de iniciar ações que não podem ser desfeitas.
O mesmo conceito aparece em integrações de mensageria. Para entender um caso específico de recebimento de eventos, veja também o guia do JSMS sobre como receber mensagens do WhatsApp no seu servidor com a Cloud API.
Vale a pena usar um webhook no n8n?
Sim, quando você precisa conectar um serviço ao n8n sem esperar por um nó pronto. O caminho básico é curto: criar o Webhook, escolher POST, testar com a URL temporária, validar o JSON e publicar o workflow com a URL de produção.
O ponto que costuma ser esquecido é a operação depois do tutorial. Um endpoint aberto, sem validação e sem tratamento de duplicidade, pode transformar uma automação útil em uma fonte de spam e registros errados. Comece com um fluxo pequeno, faça testes com dados fictícios e só depois conecte o webhook a sistemas que alteram dados ou enviam mensagens.
Perguntas frequentes
Qual é a diferença entre Test URL e Production URL no n8n?
A Test URL serve para desenvolver e depurar o workflow, enquanto a Production URL deve ser usada depois que o workflow estiver publicado ou ativo.
Posso receber dados de qualquer formulário no n8n?
Sim, desde que o formulário consiga enviar uma requisição HTTP para um endereço público e use o método e o formato esperados pelo nó Webhook.
Qual método HTTP devo usar para enviar dados de um formulário?
O método POST costuma ser a escolha mais simples para enviar dados no corpo da requisição, especialmente quando o payload está em JSON.
Um webhook do n8n é seguro por padrão?
Não necessariamente. O endpoint pode ficar público, então é importante configurar autenticação quando possível e validar os dados recebidos antes de continuar o fluxo.