Webhooks de entrada no Flow: receber, proteger e responder
Um webhook de entrada é uma URL que você entrega a outro serviço para ele avisar quando algo acontece: um formulário enviado, um pagamento, um push em um repositório. Do seu lado, um flow começa sozinho. É o trigger mais usado em qualquer ferramenta de automação e também o mais mal configurado, porque a URL fica pública na internet.
O n8n resolve isso com um nó Webhook que tem dois endereços, um de teste e um de produção, conforme a documentação do nó. A URL de teste só escuta enquanto você olha o editor. A de produção é registrada ao ativar o workflow. O Flow tem uma única URL por trigger, e o que fazer com ela se resume a quatro ajustes. Aqui estão, com exemplos para copiar.
1. Criar o trigger e copiar a URL
No Flow, crie um flow novo e escolha Webhook de entrada como trigger. Salve: só então a URL aparece, neste formato:
https://seu-dominio/api/flow/hooks/fh_xxxxxxxxxxxxxxxxxxxx
O token depois de fh_ é o segredo daquele nó. Há um por trigger, e se você apagar o nó o token vai junto. Trate como uma senha: não cole em um repositório público nem em um ticket.
Uma consequência prática: com o flow desligado, a URL responde 404. É a mesma resposta que um token inexistente recebe, então quem testa não sabe se o flow está pausado ou se a URL é inventada.
2. Escolher quais métodos aceita
O campo Aceita tem três opções: só POST (o padrão), só GET, ou GET e POST. Qualquer outro método recebe 405.
- POST para quase tudo: formulários, Stripe, GitHub, seu próprio backend.
- GET para serviços que verificam a URL antes de começar a mandar eventos, ou para um botão em um email que dispara uma ação.
- GET e POST quando você tem os dois casos na mesma URL.
O corpo é interpretado conforme o Content-Type. Com application/json vira um objeto (e se o JSON estiver quebrado, quem chama recebe 400 em vez de uma execução com lixo). Com application/x-www-form-urlencoded vira um objeto de campos. Qualquer outro tipo chega como texto. O limite é 256 KB: acima disso, 413.
3. Ler os dados nos passos seguintes
Tudo o que chega fica disponível como template nos nós seguintes:
{{trigger.body}}para o corpo, e por exemplo{{trigger.body.email}}para um campo.{{trigger.query}}para os parâmetros da URL (?origem=landing).{{trigger.headers}}para os headers.{{trigger.method}}para saber se foi GET ou POST.
Um exemplo concreto: um formulário do seu site faz POST com {"nome": "Ana", "email": "ana@exemplo.com"}. Adicione um nó CRM: criar contato com o email {{trigger.body.email}}. Se já existir um contato com esse email, o nó devolve o existente em vez de duplicar, então reenviar o formulário não suja a base. Depois some CRM: inscrever em sequência para iniciar o acompanhamento.
Para ver como ficou cada valor, abra a execução: o histórico guarda a entrada e a saída de cada passo.
4. Fechar a porta com uma credencial
Por padrão, quem tem a URL pode chamá-la. Se o serviço que chama consegue mandar um header, peça autenticação no campo Pedir autenticação. Há duas formas:
- API key em um header. Você cria uma credencial com o nome do header (por exemplo
X-Api-Key) e o valor. Toda requisição precisa trazê-lo; senão, recebe 401. - Usuário e senha (Basic). Para serviços que só sabem mandar
Authorization: Basic.
O segredo é comparado em tempo constante, e o header com a chave não é repassado ao flow, então não fica guardado no histórico de execuções. Se você apagar a credencial, a URL não se abre: fica fechada até você escolher outra. As tentativas falhas também contam contra o limite do IP, o que freia quem testa senhas.
Hoje o Flow não valida assinaturas HMAC genéricas neste trigger. Para Stripe existe um trigger próprio que verifica a assinatura com o signing secret. Se precisar verificar outra assinatura, a saída é um nó de código que a calcule, ou uma API key no header.
5. Responder com seu próprio código de status
Por padrão o webhook responde 202 de imediato e a execução continua por trás. Serve para quase tudo: o serviço de fora não fica esperando.
Quando a resposta precisa depender do resultado, mude Responde para Com o passo Responder ao webhook e adicione esse nó no final. Você escolhe o código de status, o tipo de conteúdo (JSON, texto ou HTML) e o corpo, que pode usar dados dos passos anteriores. Um caso simples:
- O Webhook de entrada recebe
{"email": "ana@exemplo.com"}. - Um nó CRM: criar contato cria ou encontra o contato.
- Responder ao webhook devolve 200 com um JSON de confirmação. Se você colocar antes um nó Filtro que corta o ramo quando
{{trigger.body.email}}não existe, pode usar outro Responder ao webhook no ramo de erro com um 422.
Os limites reais: quem chama espera até 25 segundos. Se a execução não respondeu a tempo, recebe 202 e a execução segue. Se o flow falhar, recebe 500. A resposta é entregue com Content-Security-Policy: sandbox, para que um corpo HTML montado com dados de fora não consiga rodar scripts no seu domínio.
Isso cobre verificação de endpoints, formulários que precisam de um código claro e APIs pequenas. Não cobre algo que demore um minuto: nesse caso, responda 202 e avise por outro canal quando terminar.
Limites que convém conhecer
- Cada token aceita 600 requisições por minuto. Acima disso, recebe 429.
- Cada workspace tem um teto de execuções por hora: 1000 por padrão, configurável no self-host com a variável
FLOW_RUNS_PER_HOUR. Passado o teto, o webhook responde 429 e quem chama pode tentar de novo mais tarde. - Os headers
cookie,authorizatione os de infraestrutura (x-forwarded-*e similares) são descartados antes de chegar ao flow. - Há só uma URL por trigger: não existe URL de teste separada. Para testar sem mexer na produção, monte um segundo flow com seu próprio trigger e aponte o serviço de teste para essa URL.
Checklist antes de publicar a URL
- Escolha o menor método que você precisa.
- Se o serviço permitir, exija uma API key em um header.
- Teste com
curle confira a execução no histórico. - Monte um flow de erros para saber se algo quebrar (falamos disso em Quando um flow falha).
- Guarde a URL em um gerenciador de segredos, não no chat da equipe.
No self-host, tudo isso roda no seu servidor e as execuções ficam no seu próprio banco de dados.