Webhook no n8n do zero: recebendo dados de sistemas externos

Webhook é o gatilho que faz o n8n receber dados em vez de ficar perguntando. Você cria o node, ele gera uma URL, e todo sistema que enviar dados para esse endereço dispara o fluxo na hora. É a diferença entre verificar uma caixa a cada minuto e ser avisado quando algo chega — e no custo de execuções, essa diferença é gigante.

Como funciona

Ao adicionar um node Webhook, o n8n gera duas URLs para ele: uma de teste e uma de produção. Quem envia dados para essa URL aciona o fluxo, e o conteúdo enviado vira o item que trafega pelos nodes seguintes.

É o inverso do HTTP Request: lá você chama alguém; aqui alguém chama você.

Onde os dados chegam

Este é o ponto que mais gera dúvida. O conteúdo não chega solto — vem organizado em seções:

{
  "headers": { "host": "...", ... },
  "params": {},
  "query": {},
  "body": {
    "name": "Jim",
    "age": 30,
    "city": "New York"
  }
}

O que foi enviado fica no body. Então o caminho para pegar um campo é:

{{ $json.body.name }}

Escrever {{ $json.name }} num fluxo de webhook devolve vazio, e é o erro número um de quem está começando. O campo existe — está um nível abaixo. As outras seções também são úteis: headers traz autenticação e identificação de quem chamou, e query traz o que veio na URL depois do ponto de interrogação.

Escolhendo o método

O node aceita os métodos HTTP padrão — GET, POST, PUT, PATCH, DELETE, HEAD. Por padrão ele aceita um método por vez.

Se você precisa aceitar mais de um, existe a opção Allow Multiple HTTP Methods nas configurações do node. Com ela ligada, o node passa a aceitar vários e ganha uma saída para cada método — o que permite fazer coisas diferentes conforme o verbo recebido.

Na prática: quem envia formulário e sistema que notifica evento usam POST. GET aparece em verificação de endereço e em integrações mais simples.

Testando

Duas formas diretas, ambas na documentação:

Com outro fluxo. Monte um segundo fluxo com um node HTTP Request apontando para a URL do webhook, usando o mesmo método. Útil quando você quer simular o envio repetidas vezes.

Com curl, do seu terminal:

curl --request POST https://seu-n8n.url/webhook/caminho --data 'chave=valor'

Para enviar cabeçalho junto:

curl --request GET https://seu-n8n.url/webhook/caminho --header 'chave: valor'

Protegendo o endereço

Uma URL de webhook é pública: quem souber o endereço consegue disparar o fluxo. Em fluxo que grava dado ou envia mensagem, isso importa.

As proteções disponíveis:

• Autenticação no node — exigir usuário e senha ou um valor de cabeçalho específico. Quem não enviar é recusado.

• Caminho difícil de adivinhar — o n8n gera um identificador aleatório; não troque por algo como /webhook/pedidos.

• Validar o conteúdo — antes de gravar qualquer coisa, confirme que os campos esperados existem e fazem sentido.

O que responder a quem chamou

Por padrão, o n8n responde imediatamente confirmando o recebimento, e o fluxo segue por conta própria. É o comportamento certo na maioria dos casos: quem enviou não fica esperando.

Quando o sistema que chama precisa de uma resposta com conteúdo — um formulário que mostra resultado na tela, por exemplo —, dá para configurar o node para responder ao final do fluxo, devolvendo os dados processados.

Crie o node, pegue a URL, lembre que os dados chegam em $json.body, proteja com autenticação e valide o conteúdo antes de gravar.

Perguntas frequentes