Um webhook é uma URL que recebe uma requisição HTTP quando algo acontece em outro serviço. No n8n, ele pode iniciar um fluxo de automação sem que você precise ficar consultando uma API de tempos em tempos.
Neste tutorial, você vai criar um webhook para receber um JSON, enviar uma requisição com curl e conferir o resultado no n8n. O caminho serve para testar formulários, integrações internas, notificações e protótipos de API antes de conectá-los a um serviço real.
O que é um webhook no n8n?
Imagine uma campainha: o serviço externo toca quando ocorre um evento, e o n8n começa o workflow. Isso é diferente do polling, em que seu sistema precisa perguntar repetidamente se há alguma novidade.
O nó Webhook expõe um endereço para receber requisições. A documentação do n8n informa que o caminho pode ser gerado automaticamente para evitar conflitos, mas também pode ser definido manualmente quando você precisa de uma rota estável. O nó aceita, entre outras opções, requisições GET e POST; para enviar dados estruturados, o POST com JSON é a escolha mais comum.
O n8n também permite exigir autenticação básica, por cabeçalho ou JWT. Deixar a autenticação como “None” pode ser aceitável em um teste controlado, mas é uma má ideia para uma URL pública que receberá dados de clientes.
Como criar o webhook no n8n
1. Crie um workflow
Abra o n8n, crie um workflow novo e adicione o nó Webhook. No campo HTTP Method, selecione POST. Em Path, use algo simples, como pedido-teste, ou deixe o n8n gerar um caminho.
Para este primeiro teste, mantenha a resposta simples. Você pode usar When Last Node Finishes e adicionar um nó Respond to Webhook se quiser controlar exatamente o corpo e o código retornados. A documentação oficial também oferece as opções de responder imediatamente ou devolver dados do último nó.
2. Escolha a URL de teste
O nó mostra uma Test URL e uma Production URL. Para desenvolver, clique em Listen for test event ou execute o workflow em modo de teste antes de enviar a requisição.
A URL de teste é feita para validar o payload enquanto o editor está ouvindo. Já a URL de produção é a que deve ser cadastrada no serviço externo quando o workflow estiver ativo. Confundir as duas é um dos motivos mais comuns para a integração parecer “quebrada”.
Como testar o webhook com curl
Com o n8n ouvindo a URL de teste, abra o terminal e troque o endereço abaixo pelo que aparece no seu nó:
curl -X POST 'https://SEU-N8N/webhook-test/pedido-teste' \
-H 'Content-Type: application/json' \
--data '{"cliente":"Ana","pedido":1234,"origem":"site"}'O comando envia um POST com três campos. No n8n, o conteúdo costuma aparecer dentro de $json.body, dependendo da versão e da configuração do nó. Procure a execução recebida e abra os dados de entrada para confirmar se os nomes e tipos chegaram como esperado.
O curl também tem a opção --json, que a documentação oficial descreve como um atalho para enviar dados JSON e definir os cabeçalhos correspondentes. Se sua instalação do curl não reconhecer essa opção, use o formato com -H e --data mostrado acima.
Teste versus produção: qual URL usar?
| URL | Quando usar | O que conferir |
|---|---|---|
| Teste | Desenvolvimento e inspeção do payload | Editor ouvindo e execução de teste ativa |
| Produção | Integração que ficará funcionando continuamente | Workflow ativo e endereço cadastrado no serviço externo |
Uma forma segura de avançar é repetir o mesmo comando primeiro na URL de teste e, depois de conferir o JSON, trocar apenas o trecho webhook-test pela URL de produção. Não publique a URL de teste em um formulário, aplicativo ou serviço que precise funcionar sem o editor aberto.
Como proteger um webhook público
Uma URL de webhook é um ponto de entrada. Se alguém descobrir o endereço, poderá tentar enviar requisições. Para reduzir esse risco:
- ative autenticação básica, por cabeçalho ou JWT quando o sistema remetente suportar;
- use um caminho difícil de adivinhar e não coloque dados sensíveis nele;
- valide campos obrigatórios antes de executar ações irreversíveis;
- limite origem ou IP quando isso fizer sentido para sua infraestrutura;
- registre erros e evite devolver informações internas na resposta.
O n8n documenta ainda uma lista de IPs permitidos e uma condição Only Run If para filtrar requisições. Essas camadas não substituem a autenticação: elas ajudam a reduzir o volume de chamadas indevidas e a impedir que qualquer payload passe direto para a automação.
Se você pretende conectar essa entrada a uma aprovação ou a uma sequência mais longa, vale complementar com o guia do JSMS sobre como criar uma aprovação humana no n8n antes da automação. O webhook recebe o pedido; a aprovação evita que todo pedido recebido vire ação automaticamente.
Erros comuns e como corrigir
O n8n não recebe nada
Confira se você clicou para ouvir o evento de teste, se o método é POST e se o comando usa exatamente a URL exibida no nó. Também verifique se o n8n está acessível pela internet: localhost só funciona para chamadas feitas na mesma máquina.
Recebi 404 ou “not found”
O caminho pode estar errado, o workflow pode não estar ativo ou você pode ter usado a URL de produção antes de ativá-lo. Copie o endereço diretamente do nó em vez de digitá-lo manualmente.
Recebi 401 ou 403
Isso normalmente aponta para autenticação ou restrição de origem. Revise o tipo de credencial escolhido no Webhook e confira se o cabeçalho exigido está presente. Não remova a proteção apenas para “fazer funcionar” sem entender por que a chamada foi recusada.
O webhook responde, mas os campos estão vazios
Confirme o cabeçalho Content-Type: application/json e veja se o corpo é um JSON válido. Chaves com grafia diferente também causam problemas: cliente e customer são campos distintos para a automação.
Como saber se o teste deu certo
O teste está no caminho certo quando três coisas acontecem: o terminal recebe um código HTTP de sucesso, uma execução aparece no n8n e o painel mostra o JSON com os valores enviados. Depois, adicione um nó simples — como uma resposta, registro ou mensagem de teste — para confirmar que o workflow continua a partir do Webhook.
Antes de ligar o endpoint a pagamentos, pedidos, exclusões ou mensagens para clientes, repita o teste com campos ausentes, valores inesperados e chamadas duplicadas. Automação boa não é a que apenas funciona no cenário feliz; é a que falha de forma previsível quando alguém envia dados ruins.
Perguntas frequentes
Preciso saber programar para criar um webhook no n8n?
Não. Você consegue criar o gatilho pela interface e testar com um comando pronto. Conhecer JSON e HTTP ajuda a investigar erros, mas não é necessário escrever um aplicativo inteiro.
Posso usar GET em vez de POST?
Sim, quando o serviço remetente envia dados pela URL ou quando você está criando uma consulta simples. Para dados estruturados e informações que não deveriam ficar na URL, prefira POST.
A URL de teste funciona para sempre?
Ela serve para desenvolvimento enquanto o n8n está ouvindo o evento de teste. Para uma integração contínua, use a URL de produção com o workflow ativo.
O webhook do n8n é seguro por padrão?
Não trate uma URL pública como secreta. Configure autenticação, valide o conteúdo recebido e limite quem pode chamar o endpoint sempre que possível.