Para criar um webhook funcional no n8n, adicione um nó Webhook, escolha o método HTTP e o caminho, conecte um nó de resposta e teste primeiro a URL de teste. Depois de confirmar o retorno, ative o workflow e troque para a URL de produção. Esse fluxo transforma uma requisição HTTP em uma entrada para automações, integrações com formulários, sistemas internos e serviços de mensageria.
Este tutorial mostra um cenário pequeno, mas completo: receber um pedido POST com dados de um cliente, validar se existe um nome, montar uma resposta e devolvê-la em JSON. A ideia não é apenas clicar nos nós, mas deixar claro o que testar, qual URL usar em cada fase e como investigar quando a integração parece não responder.
O que você vai construir
Ao final, o workflow terá quatro responsabilidades: receber a chamada HTTP, ler o corpo enviado, criar uma saída previsível e responder ao sistema que fez a chamada. O desenho básico é:
Webhook (POST) → Edit Fields (Set) → Respond to Webhook
O nó Webhook é o ponto de entrada. O nó Edit Fields (Set) organiza os campos de saída sem exigir código. O Respond to Webhook controla a resposta HTTP, em vez de depender apenas do último nó executado. Para entender a diferença entre o conceito geral e este uso prático, veja também o artigo do JSMS sobre o que é webhook e como funciona nas integrações.
Pré-requisitos
Você precisa de uma instância do n8n acessível pelo navegador e permissão para criar e ativar workflows. Pode ser o n8n Cloud ou uma instalação própria. No caso de hospedagem própria, a documentação oficial recomenda Docker para muitos cenários de self-hosting, mas a forma de instalação não muda os campos usados neste tutorial.
Também tenha um cliente HTTP para fazer o teste. Pode ser o cURL, o Postman, o Insomnia ou outro sistema capaz de enviar uma requisição POST. Você não precisa de uma API externa nem de credenciais para o exemplo básico. Se o n8n estiver rodando apenas em localhost, um serviço externo não conseguirá acessá-lo diretamente; para uma integração real, use um endereço publicado com HTTPS ou a infraestrutura de túnel e proxy adequada à sua instalação.
1. Crie o workflow e configure o Webhook
Abra o n8n, crie um workflow novo e adicione o nó Webhook. No campo HTTP Method, escolha POST. Em Path, use um caminho simples, como cadastro-demo. O caminho identifica o endpoint dentro da URL do n8n; não coloque aqui o domínio completo nem espaços.
Para este primeiro teste, deixe a autenticação desativada somente se o endpoint não estiver recebendo dados sensíveis. Em produção, avalie a autenticação disponível no seu ambiente e aplique uma camada adicional quando o sistema que fará a chamada puder enviar credenciais. Um webhook público sem autenticação pode ser descoberto e abusado, mesmo que o workflow faça apenas uma operação simples.
O n8n exibe duas URLs para o Webhook: Test URL e Production URL. A URL de teste serve para desenvolver e observar a execução enquanto o workflow está sendo executado no editor. A de produção é a que deve ser entregue a outro sistema depois que o workflow estiver salvo e ativo.
2. Conecte um nó para organizar os dados
Arraste o nó Edit Fields (Set) para o canvas e conecte a saída do Webhook a ele. Crie três campos para a resposta: ok com o valor booleano true, mensagem com o texto Cadastro recebido e nome_recebido usando uma expressão que leia o corpo da requisição:
{{ $json.body.nome }}
O formato exato do item recebido pode variar conforme o cliente, o tipo de conteúdo e a versão configurada. Por isso, não digite a expressão no escuro: primeiro execute a URL de teste com um corpo conhecido, abra a saída do Webhook e confirme onde o n8n colocou os dados. Em uma chamada JSON comum, o corpo costuma aparecer em body, mas a saída observada no próprio workflow é a referência autoritativa para a sua configuração.
Se você preferir preservar outros campos recebidos, mantenha a opção de incluir os campos de entrada quando ela estiver disponível no nó. Para este exercício, uma resposta pequena é melhor: ela facilita a leitura no Postman e deixa evidente o que o endpoint devolveu.
3. Configure a resposta HTTP
Adicione o nó Respond to Webhook depois do Edit Fields. No Webhook, selecione o modo de resposta que usa esse nó. No Respond to Webhook, escolha responder com o JSON do item. Assim, o objeto produzido pelo nó anterior será devolvido ao cliente que fez a chamada.
Se a interface mostrar um campo para código de resposta, use 200 para o teste bem-sucedido. Para um endpoint que cria um recurso, outros códigos podem ser mais apropriados, mas não invente um significado: escolha o status conforme o contrato da integração. Também confira o cabeçalho de tipo de conteúdo. A resposta precisa ser interpretável como JSON pelo sistema consumidor.
| Elemento | Configuração do tutorial | Função |
|---|---|---|
| Webhook | POST /cadastro-demo | Recebe a requisição |
| Edit Fields (Set) | ok, mensagem, nome_recebido | Monta o JSON |
| Respond to Webhook | Resposta JSON, HTTP 200 | Devolve o resultado |
4. Faça o teste com a URL correta
Salve o workflow. Para testar dentro do editor, clique para executar o workflow e deixe o Webhook aguardando uma chamada. Copie a Test URL mostrada pelo nó e use-a no seu cliente HTTP. Um exemplo com cURL é:
curl -i -X POST "COLE_A_TEST_URL_AQUI" \
-H "Content-Type: application/json" \
--data "{\"nome\":\"Ana\"}"O retorno esperado é uma resposta HTTP bem-sucedida com um JSON que contenha os campos definidos no nó Set, incluindo o nome recebido. O ponto importante do teste é conferir três coisas ao mesmo tempo: a requisição chegou ao Webhook, o item exibido no painel contém o corpo enviado e o Respond to Webhook devolveu um resultado ao cliente. Não considere apenas a execução verde no editor como prova de que o consumidor recebeu a resposta.
5. Passe para a URL de produção
Quando o teste funcionar, salve novamente e ative o workflow. Copie a Production URL do Webhook e faça uma segunda requisição usando exatamente o mesmo método, caminho e corpo. A URL de produção não é um substituto para o teste enquanto o workflow está inativo; ela depende do workflow ativo para atender chamadas regulares.
Antes de entregar essa URL a um formulário ou aplicação, defina um contrato: quais campos são obrigatórios, qual resposta representa sucesso, quais erros serão retornados e como repetição de chamadas será tratada. O exemplo aceita um nome, mas ainda não valida de forma completa. Em uma automação real, adicione validação, limite de tamanho, autenticação, registro de falhas e uma estratégia para evitar duplicação quando o remetente repetir a requisição.
Erros comuns e como evitá-los
Usar a URL de teste sem executar o workflow
A URL de teste é feita para o modo de desenvolvimento. Se você disparar a chamada sem deixar o Webhook aguardando, o n8n pode não capturar o evento. Execute o workflow antes da chamada e observe o painel do nó.
Usar a URL de produção com o workflow inativo
Depois do desenvolvimento, ative o workflow e use a URL de produção. Se o endpoint funcionou no editor, mas falha quando chamado de outro sistema, verifique primeiro o status de ativação e se o domínio está acessível pela internet.
Escolher método HTTP diferente do enviado
Um Webhook configurado para POST não deve ser testado com GET por engano. Confira o método no cliente, no nó e no contrato do serviço. O nó possui saídas e comportamentos ligados ao método configurado.
Ler o campo no caminho errado
Se $json.body.nome retornar vazio, abra os dados reais da execução e localize o campo. Verifique também o cabeçalho Content-Type. Enviar texto puro quando o workflow espera JSON pode mudar a estrutura recebida.
Esperar uma resposta, mas não configurar o Respond to Webhook
O Webhook pode responder imediatamente ou quando o último nó termina, conforme a configuração. Se você precisa controlar corpo e status, selecione o modo que usa o Respond to Webhook e mantenha esse nó conectado ao caminho executado.
Como tornar o fluxo adequado para produção
O exemplo é um ponto de partida, não um endpoint pronto para dados críticos. Use HTTPS, autenticação e validação de entrada. Não coloque senhas no corpo do workflow nem em mensagens de erro. Se o webhook acionar envio de WhatsApp, gravação em CRM ou outra operação irreversível, registre um identificador da chamada e trate reenvios de forma idempotente.
Também vale separar o recebimento da execução demorada. Se uma tarefa levar muito tempo, devolver uma resposta rápida e processar o trabalho em seguida pode ser melhor do que manter o cliente esperando. A decisão depende do contrato da aplicação e da capacidade de monitorar falhas. O n8n oferece nós e configurações para cenários mais avançados, mas cada um deve ser testado com o serviço consumidor antes de ser colocado em produção.
FAQ
Posso chamar um webhook do n8n a partir de um formulário?
Sim. O formulário precisa enviar uma requisição HTTP para a URL do Webhook, com método e formato compatíveis. Se enviar JSON, inclua o cabeçalho Content-Type correspondente e confirme no painel do n8n como os campos foram recebidos.
Qual é a diferença entre Test URL e Production URL?
A Test URL é usada durante a construção, com o workflow sendo executado no editor. A Production URL atende o workflow salvo e ativo. Use a primeira para depuração e a segunda na integração definitiva.
Preciso usar o Respond to Webhook?
Não em todos os casos. Para respostas simples, o Webhook pode responder de outras formas. Use o Respond to Webhook quando precisar controlar explicitamente o corpo, o status ou o momento da resposta.