Para proteger um webhook público no n8n, configure autenticação por cabeçalho, valide o segredo antes de processar os dados e só depois encaminhe a execução para as etapas da automação. Esse desenho evita que qualquer pessoa que descubra a URL consiga disparar o fluxo. O procedimento abaixo usa recursos documentados do n8n e pode ser aplicado tanto em uma instância hospedada quanto em uma instalação própria, desde que o endereço público esteja acessível.
O webhook é uma porta de entrada para o workflow. Ele recebe uma requisição HTTP e transforma os dados recebidos em entrada para os nós seguintes. Como a URL de produção pode ser chamada por outro sistema sem abrir a interface do n8n, ela precisa ser tratada como uma API: deve ter uma forma de autenticação, uma resposta previsível e uma rotina para lidar com falhas. Se você ainda está começando, veja também o guia do JSMS sobre como criar um webhook no n8n e responder dados em JSON; aqui o foco é acrescentar uma camada de proteção ao fluxo.
O que você vai montar
O resultado será um workflow com quatro partes: um nó Webhook para receber a chamada, um nó If para conferir um segredo em um cabeçalho, um caminho de erro que devolve uma resposta HTTP sem executar a lógica principal e, no caminho autorizado, um nó de processamento seguido de Respond to Webhook. O segredo não ficará exposto na URL nem será colocado diretamente em um campo visível para quem chama o endpoint.
Esse modelo é adequado para integrações internas, formulários, sistemas próprios e serviços que permitem enviar cabeçalhos HTTP. Ele não substitui uma solução completa de identidade quando o endpoint precisa atender muitos clientes, emitir tokens individuais, revogar acessos por usuário ou registrar permissões detalhadas. Nesses casos, considere um gateway de API ou autenticação baseada em tokens rotativos.
Pré-requisitos
- Uma conta no n8n Cloud ou uma instância própria do n8n acessível pela internet.
- Permissão para criar e ativar workflows.
- Um cliente HTTP para teste, como cURL, Postman ou a ferramenta de requisições do sistema que fará a integração.
- Um segredo longo e aleatório, armazenado fora do código da automação. Use um gerenciador de senhas ou um cofre de segredos; não reutilize uma senha de usuário.
- Conhecimento básico de expressões e nós no editor do n8n.
O n8n oferece duas URLs no nó Webhook: uma de teste e outra de produção. A URL de teste é útil durante a montagem, porque permite observar os dados no editor quando o workflow está aguardando uma chamada. A URL de produção deve ser usada somente depois que o workflow estiver ativo. Não confunda as duas: enviar dados para a URL errada é uma das causas mais comuns de um teste aparentemente não funcionar.
1. Crie o nó Webhook
Abra um workflow novo, adicione o nó Webhook e escolha o método HTTP que a origem usará. Para receber um evento com informações no corpo, POST costuma ser a escolha mais apropriada. Defina um caminho específico, como pedidos-seguros, em vez de usar um nome genérico. O caminho não é uma senha, mas ajuda a identificar a finalidade do endpoint e a evitar colisões.
Na configuração de resposta, selecione a opção que permite responder por meio do nó Respond to Webhook. Essa escolha dá controle sobre o status HTTP e o corpo devolvido ao sistema chamador. Se a sua versão ou plano apresentar os campos com nomes ligeiramente diferentes, confirme a descrição exibida no próprio editor antes de salvar. A documentação oficial do nó Webhook explica a diferença entre as URLs e os parâmetros disponíveis.
2. Defina a autenticação por cabeçalho
No nó Webhook, procure a área de autenticação e selecione a modalidade baseada em cabeçalho, quando ela estiver disponível na sua versão. Cadastre um nome de cabeçalho que não seja ambíguo, por exemplo X-Webhook-Secret, e informe o segredo no campo apropriado. O objetivo é fazer o n8n rejeitar chamadas sem o cabeçalho esperado antes que os dados avancem no workflow.
Se o editor oferecer autenticação nativa por credencial de webhook, prefira essa opção a comparar o segredo em um nó comum. Ela centraliza a regra de acesso e reduz a chance de um caminho do workflow processar dados antes da validação. Caso sua instalação não ofereça esse recurso, use a alternativa descrita na próxima etapa: leia o cabeçalho recebido e compare-o em um nó If antes de qualquer ação externa.
Não coloque o segredo em parâmetros de consulta, como ?token=.... URLs podem aparecer no histórico do navegador, em logs de proxy, em ferramentas de monitoramento e em mensagens de suporte. Um cabeçalho também pode ser registrado por algum componente intermediário, mas é uma opção melhor para não espalhar o valor pela própria URL; use HTTPS e revise os logs da infraestrutura.
3. Valide o cabeçalho antes da lógica principal
Para a alternativa manual, adicione um nó If imediatamente depois do Webhook. Na primeira condição, selecione uma expressão que leia o cabeçalho recebido. Em workflows do n8n, os metadados da requisição ficam disponíveis na entrada do Webhook; use o painel de dados do editor para confirmar o caminho exato exibido pela sua versão, em vez de copiar uma expressão sem conferir a estrutura real.
Compare o valor recebido com o segredo armazenado de forma segura. Não faça uma comparação parcial, não aceite valor vazio e não use uma condição que apenas verifique se o cabeçalho existe. A regra precisa ser equivalente a: “o cabeçalho existe e é exatamente igual ao valor autorizado”. Se a origem enviar mais de um formato de token, normalize essa decisão explicitamente e documente qual formato é aceito.
Conecte a saída falsa do If a um nó Respond to Webhook configurado para devolver 401 Unauthorized ou 403 Forbidden, conforme a política da sua integração. Um 401 comunica falta de autenticação; um 403 é apropriado quando a identidade foi reconhecida, mas não tem permissão. Não devolva o segredo, o cabeçalho recebido ou detalhes internos do workflow no corpo da resposta.
4. Processe somente a saída autorizada
Ligue a saída verdadeira do If ao próximo nó do fluxo. Ele pode validar o JSON, transformar campos, consultar um CRM ou iniciar outra etapa, dependendo do objetivo da automação. Faça a validação do formato recebido antes de gravar dados ou chamar serviços externos. Por exemplo, confirme se existe um identificador de pedido, se o e-mail tem o formato esperado e se números estão dentro dos limites aceitos.
Depois da lógica autorizada, adicione outro Respond to Webhook. Retorne um status coerente, como 200 para uma operação concluída ou 202 quando o evento foi aceito para processamento posterior. O corpo pode conter apenas um identificador de rastreamento e uma mensagem curta. Evite devolver o conteúdo inteiro recebido se ele contiver dados pessoais ou informações internas.
Se o processamento demorar, avalie responder rapidamente e mover o trabalho pesado para uma fila ou subworkflow. O sistema que chamou o webhook pode ter um tempo limite curto e repetir a requisição se não receber resposta. Essa repetição pode criar pedidos duplicados. Para operações que não podem ser repetidas sem risco, use um identificador idempotente e verifique se ele já foi processado antes de executar a ação.
5. Teste com a URL de teste
Salve o workflow, clique para executar ou aguardar o teste no editor e copie a Test URL exibida no nó Webhook. Em outro terminal, envie uma requisição que inclua o cabeçalho correto. Um exemplo genérico é:
curl -i -X POST 'URL_DE_TESTE' \\
-H 'Content-Type: application/json' \\
-H 'X-Webhook-Secret: SEU_SEGREDO' \\
--data '{"evento":"teste","id":"abc-123"}'Substitua os dois valores indicados, sem deixar espaços extras no segredo. O teste de sucesso tem três sinais: o editor mostra a execução no caminho verdadeiro do If, a etapa de processamento recebe o JSON esperado e o cliente HTTP recebe o status configurado no Respond to Webhook. Faça também uma chamada sem o cabeçalho e outra com um valor incorreto. Essas duas devem parar no caminho falso e não podem disparar a ação principal.
Depois de confirmar o comportamento, troque para a Production URL, ative o workflow e repita a chamada usando a URL de produção. A documentação de desenvolvimento de webhooks do n8n recomenda separar esse ciclo de teste do uso real. Nunca deixe o sistema de produção apontando para a URL de teste, que depende de uma execução de teste aberta no editor.
Erros comuns e como evitá-los
O workflow não recebe a requisição
Verifique se você está usando a URL correspondente ao ambiente, se o workflow está ativo no caso da URL de produção e se o servidor é acessível externamente. Em uma instalação própria, confira DNS, proxy reverso, certificado TLS e firewall. Também confirme o método: um endpoint configurado como POST não deve ser testado com GET.
A validação sempre retorna falso
Abra os dados da execução e confira o nome exato do cabeçalho, incluindo maiúsculas, hífens e o caminho usado na expressão. Compare o valor real recebido com o valor configurado sem aspas acidentais, quebras de linha ou espaços no início e no fim. Faça um teste controlado e não registre o segredo em nós de depuração ou mensagens de erro.
A chamada retorna sucesso, mas nada é processado
Isso pode acontecer quando o Respond to Webhook está conectado antes da ação, quando o If está ligado à saída errada ou quando uma condição de validação do payload bloqueia o fluxo. Inspecione a execução nó a nó. O retorno HTTP não prova que uma etapa posterior terminou: escolha conscientemente entre resposta síncrona e aceitação assíncrona.
O evento é executado duas vezes
Repetições podem vir de timeout do cliente, de um provedor que tenta novamente após uma resposta não recebida ou de um botão de teste acionado mais de uma vez. Grave uma chave idempotente, trate duplicidades e configure alertas. O n8n também documenta workflows de erro com o nó Error Trigger, que pode ajudar a avisar a equipe quando uma execução falhar.
Cuidados antes de colocar em produção
Use HTTPS, limite os dados aceitos e mantenha o n8n atualizado conforme a política da sua operação. Restrinja por IP apenas quando a origem tiver endereços estáveis; essa medida não substitui a autenticação e pode quebrar integrações legítimas quando o provedor mudar a infraestrutura. Para parceiros diferentes, prefira credenciais ou tokens separados, pois assim é possível revogar um acesso sem interromper todos os demais.
Revise quem pode visualizar credenciais e execuções, porque dados de entrada podem conter informações sensíveis. Defina quanto tempo as execuções devem ser mantidas e remova logs que não sejam necessários. Monitore respostas 4xx e 5xx, volume de chamadas e tempo de processamento. Um endpoint protegido não é apenas aquele que exige segredo: ele também precisa ser observável, limitar abuso e falhar sem expor informações internas.
Conclusão
A sequência mais segura para um webhook simples no n8n é receber a requisição, autenticar o cabeçalho, validar o corpo, executar a automação e responder com o mínimo de informação necessário. Teste primeiro a URL de teste com chamadas autorizadas e não autorizadas; só depois ative o workflow e migre para a URL de produção. Quando o fluxo crescer, acrescente idempotência, separação de credenciais, monitoramento e um mecanismo de tratamento de erros. Assim, o webhook deixa de ser apenas uma URL que dispara nós e passa a funcionar como uma integração controlada.
Perguntas frequentes
Posso usar a URL de teste em uma integração real?
Não é recomendado. A URL de teste serve para desenvolvimento e depende de uma execução de teste aguardando a chamada. Para uso real, ative o workflow e use a URL de produção.
O segredo no cabeçalho substitui HTTPS?
Não. O segredo autentica a chamada, enquanto o HTTPS protege o transporte contra leitura e alteração no caminho. Use os dois.
Qual status devo devolver quando o evento foi aceito?
Use 200 quando a operação terminou e 202 quando a requisição foi aceita para processamento posterior. O importante é alinhar o status ao comportamento real do workflow.