Conteúdo

Tutorial de Webhook no n8n: receba e responda a dados externos

Webhook permite que um serviço externo «notifique» o n8n quando um evento acontece. Por exemplo:

Alguém envia um formulário no site
Uma plataforma de pagamentos notifica que o pagamento foi aprovado
Há um novo Pull Request no GitHub
Um programa que você escreveu precisa iniciar um fluxo do n8n

O nó Webhook do n8n gera uma URL. Qualquer solicitação HTTP enviada para ela inicia um fluxo de trabalho.

Criar um Webhook

Adicione um fluxo de trabalho e escolha Webhook como primeiro nó.
Configure:
- HTTP Method: geralmente POST
- Path: caminho da URL, por exemplo, contact-form
- Respond: quando responder (veja a explicação abaixo)

Acima do nó, você verá duas URLs:

URL	Formato	Quando fica disponível
Test URL	`https://seu-dominio/webhook-test/contact-form`	Recebe uma solicitação depois que você clica em «Listen for test event»
Production URL	`https://seu-dominio/webhook/contact-form`	Depois que o fluxo de trabalho é publicado

Nó Webhook exibindo Test URL e Production URL — Nó Webhook: alterne entre Test URL e Production URL na parte superior. A URL exibida aqui usa localhost, o que significa que ainda não foi configurada uma URL pública

O erro mais comum é configurar um serviço externo com a Test URL e, depois de publicar o fluxo de trabalho, não receber os dados. Para uso em produção, troque sempre pela Production URL.

Testar

Clique em Listen for test event.
Envie uma solicitação pelo terminal:

curl -X POST https://seu-dominio/webhook-test/contact-form \
  -H "Content-Type: application/json" \
  -d '{"name": "João da Silva", "email": "joao@example.com", "message": "Gostaria de solicitar um orçamento"}'

Os dados recebidos aparecerão em OUTPUT no nó Webhook:

{
  "headers": { "content-type": "application/json", "...": "..." },
  "params": {},
  "query": {},
  "body": {
    "name": "João da Silva",
    "email": "ming@example.com",
    "message": "Gostaria de solicitar um orçamento"
  }
}

Nos nós seguintes, use {{ $json.body.name }} para ler os dados enviados. Os parâmetros da URL (como ?id=123) ficam em {{ $json.query.id }}.

Como responder

A opção Respond define quando o n8n responde e o que retorna para quem fez a chamada:

Opção	Comportamento
Immediately	Responde assim que recebe a solicitação; o fluxo de trabalho continua em segundo plano
When Last Node Finishes	Espera o fluxo inteiro terminar e retorna os dados do último nó
Using 'Respond to Webhook' Node	O nó Respond to Webhook no fluxo define o conteúdo da resposta

Se quem fez a chamada só precisa saber que a solicitação foi recebida (por exemplo, uma notificação de pagamento), escolha Immediately. Para retornar o resultado do processamento (por exemplo, criar uma API), use o nó Respond to Webhook.

Criar uma API simples com o n8n

[Webhook GET /price] ─▶ [Google Sheets consulta] ─▶ [Respond to Webhook]

Fluxo formado por Webhook, Edit Fields e Respond to Webhook — Webhook → organizar os dados → Respond to Webhook retorna JSON

No nó Respond to Webhook, você pode configurar:

Respond With: JSON, texto, arquivo binário ou redirecionamento
Response Code: por exemplo, 200 ou 404
Response Headers: por exemplo, cabeçalhos CORS



{ "product": "{{ $json.name }}", "price": {{ $json.price }} }

Parâmetros de caminho

O Path pode conter variáveis:

orders/:orderId

Ao chamar /webhook/orders/A123, {{ $json.params.orderId }} será A123.

Validar solicitações

A Production URL é pública, então qualquer pessoa que saiba o endereço pode fazer chamadas. Para protegê-la:

Use a opção Authentication: Basic Auth, Header Auth ou JWT Auth. Por exemplo, com Header Auth, defina o nome X-API-Key; quem fizer a chamada precisará enviar o valor correto.
Valide a assinatura: muitos serviços (Stripe, GitHub, LINE etc.) incluem uma assinatura no cabeçalho. Você pode validá-la com um nó Code.
Use uma lista de IPs permitidos: configure IP(s) Whitelist nas Options do Webhook.
Use no caminho uma sequência aleatória difícil de adivinhar.

Receber arquivos

Quando um formulário envia arquivos (multipart/form-data), eles aparecem nos dados binários. Você pode conectá-los diretamente a nós como Google Drive e Extract from File.

Permitir que serviços externos acessem seu n8n

Os serviços externos precisam conseguir acessar o n8n pela rede:

Implantação em produção: use um servidor com domínio e HTTPS e configure corretamente as variáveis de ambiente da URL do Webhook. Caso contrário, o n8n exibirá um endereço como http://localhost:5678/.... Veja Implantação própria.
Teste local: use ferramentas como Cloudflare Tunnel ou ngrok para expor temporariamente a porta 5678 à internet.

Problemas comuns

404: The requested webhook is not registered

Ao usar a Test URL: você não clicou em Listen for test event antes de enviar a solicitação, ou ela já foi recebida uma vez.
Ao usar a Production URL: o fluxo de trabalho não foi publicado.
O método HTTP não corresponde (por exemplo, o nó está configurado para POST, mas você chamou com GET).

O body recebido está vazio

Confirme se quem fez a chamada enviou o cabeçalho Content-Type: application/json.

O serviço externo informa que a solicitação expirou

Você selecionou When Last Node Finishes e o fluxo demora demais. Mude para Immediately ou encurte o fluxo.

Atualizado 12 de outubro de 2026