n8n avançado na prática: gatilhos Webhook e ramificações condicionais com IF/Switch

O botão laranja “Test Workflow” já tinha sido pressionado pela décima sétima vez.

Era preciso clicar nele manualmente a cada execução. Será que isso não podia funcionar como uma API de verdade, em que alguém faz uma chamada e tudo começa a rodar sozinho? Foi então que descobri que o n8n tem algo chamado Webhook — em termos simples, uma campainha: alguém toca, e o workflow entra em ação.

Este artigo explica como instalar essa “campainha” e, depois, encaminhar cada visitante para um caminho diferente. Se você já sabe usar os nós básicos do n8n, mas sente que seus workflows ficam sempre “esperando passivamente”, este guia pode abrir novas possibilidades.

Vamos ver:

• como configurar aqueles parâmetros do nó Webhook que parecem confusos à primeira vista
• quando usar IF e quando usar Switch
• um exemplo completo de processamento de pedidos, pronto para você aproveitar
• os cuidados necessários para não tropeçar em produção

1. Configuração avançada do nó Webhook

Antes de tudo: Webhook e gatilho agendado são coisas completamente diferentes.

Um gatilho agendado funciona como um despertador: toca de tempos em tempos, mesmo que nada tenha acontecido. O Webhook é uma campainha: só toca quando alguém aperta — isso é o que chamamos de arquitetura orientada a eventos. Com uma campainha, você não precisa ir até a porta a cada cinco minutos para ver se a encomenda chegou; quando o entregador chega, ele toca e você fica sabendo. Segundo os dados oficiais, Webhooks podem reduzir em 90% a 95% o custo de polling. Em outras palavras, economizam recursos e tempo.

1.1 Qual método HTTP escolher

Ao abrir o nó Webhook, o primeiro campo é HTTP Method. O n8n aceita os métodos padrão DELETE, GET, HEAD, PATCH, POST e PUT.

Qual escolher? Depende do que você quer fazer:

• POST: receber dados, como o envio de um formulário ou a notificação de um novo pedido. É o uso mais comum.
• GET: fazer um acionamento simples, como gerar um link curto que executa o workflow quando o usuário clica.
• PUT/PATCH: atualizar dados, como alterar o status de um pedido.

Na maioria das vezes uso POST, porque ele permite receber dados no body.

1.2 Há quatro modos de resposta

O parâmetro “Response Mode” define como o n8n responde a quem fez a chamada:

Há uma armadilha: se você escolher “Immediately”, quem fez a chamada recebe o 200 e segue em frente, mas não ficará sabendo se um nó posterior falhar. Por isso, tarefas em segundo plano devem ter um mecanismo de notificação de erros.

1.3 Parâmetros de rota no estilo RESTful

O parâmetro Path aceita rotas dinâmicas, como orders/:orderId. O nome depois dos dois-pontos vira uma variável, e o valor é extraído automaticamente da URL.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Por exemplo, ao chamar /orders/12345, você pode acessar 12345 no workflow usando {{ $params.orderId }}. Isso fica bem mais limpo do que enviar tudo pela query string.

1.4 Limite do tamanho do payload

O tamanho máximo padrão do payload de um Webhook é 16 MB. Acima disso, ocorre um erro.

Se realmente precisar enviar um arquivo grande, há duas opções:

1. alterar a variável de ambiente N8N_PAYLOAD_SIZE_MAX
2. fazer upload do arquivo para um armazenamento de objetos e enviar apenas a URL ao Webhook

Na prática, 16 MB bastam para a maioria dos cenários. Quando for necessário transferir arquivos grandes, a segunda opção é mais confiável.

2. IF vs. Switch: como escolher o nó de ramificação condicional

Esses dois nós parecem fazer a mesma coisa, pois ambos encaminham dados por caminhos diferentes. Mas uma escolha ruim traz bastante dor de cabeça: você pode acabar aninhando tantos IFs que o workflow vira um prato de espaguete, ou passar um tempão configurando um Switch quando só precisava de duas ramificações.

2.1 Nó IF: uma escolha binária

O nó IF tem apenas duas saídas: true e false.

É como perguntar ao entregador na porta: “É um produto refrigerado?”. Se for, vai para a geladeira; se não for, fica na entrada. Simples e direto.

O IF aceita vários tipos de condição: String, Number, Date & Time, Boolean, Array e Object. Por exemplo:

• String: contains, starts with, ends with, matches regex
• Number: is greater than, is less than
• Boolean: is true, is false
• Array: contains, length greater than

2.2 Nó Switch: múltiplos caminhos

O nó Switch pode ter várias saídas. Ele é indicado para situações como “De qual departamento você é?” — o Financeiro segue por um caminho, a Tecnologia por outro e as Operações por um terceiro.

O Switch tem dois modos:

• Rules: funciona como o preenchimento de um formulário, com uma condição para cada saída. É visual e adequado para iniciantes.
• Expression: usa uma expressão JavaScript que retorna o número da saída. É flexível e adequado para lógicas complexas.

2.3 Qual escolher? Consulte esta tabela

Uma dica: se você perceber que colocou um IF depois de outro IF, e depois mais um IF… pare. É hora de usar Switch.

2.4 Comparação de vários tipos de dados

Tanto o IF quanto o Switch aceitam comparações com estes tipos:

• String: exists, is empty, contains, matches regex…
• Number: maior que, menor que, igual a…
• Date & Time: anterior ou posterior a outra data
• Boolean: verdadeiro ou falso
• Array: tamanho ou presença de determinado elemento
• Object: existe, vazio ou não vazio

Date & Time é especialmente útil. Para verificar se um pedido está atrasado, por exemplo, basta comparar as datas.

3. Exemplo prático: processamento automático do status de pedidos

Vou contar um caso real. Um amigo tem uma pequena loja virtual e processava todos os pedidos manualmente: consultava o painel, enviava notificações e fazia ligações. Eu disse que o n8n poderia cuidar disso, mas ele ficou desconfiado.

Duas semanas depois, o pessoal do estoque perguntou: “Como é que, de repente, nenhum pedido está passando batido?”.

3.1 O que precisamos fazer

O requisito é simples:

• novo pedido (pending) → notificar o estoque para separar os produtos
• pagamento confirmado (paid) → enviar um e-mail de confirmação ao cliente
• pedido enviado (shipped) → atualizar os dados de rastreamento
• pedido cancelado (cancelled) → processar o reembolso

São quatro estados, portanto o nó Switch é perfeito para encaminhá-los.

3.2 Configuração do Webhook

Primeiro, configure o nó Webhook:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

• HTTP Method: POST
• Path: orders/:orderId
• Response Mode: When Last Node Finishes (precisamos retornar o resultado do processamento)
• Authentication: Header Auth

Na parte de segurança, usamos Header Auth com um header personalizado chamado X-Shop-Secret, cujo valor é uma sequência aleatória. Somente sistemas que conhecem esse secret podem fazer a chamada.

3.3 Lógica de ramificação do nó Switch

Configure o Switch no modo Rules, com uma regra para cada um dos quatro estados:

Regra 1: {{ $json.status }} equals "pending" → saída: pending
Regra 2: {{ $json.status }} equals "paid" → saída: paid
Regra 3: {{ $json.status }} equals "shipped" → saída: shipped
Regra 4: {{ $json.status }} equals "cancelled" → saída: cancelled

Defina Fallback Output como Extra Output. Assim, se aparecer um estado inesperado, como “unknown”, o workflow não ficará travado.

3.4 JSON completo do workflow

Você pode importar este exemplo diretamente no n8n:

{
  "name": "Order Processing",
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300],
      "parameters": {
        "httpMethod": "POST",
        "path": "orders/:orderId",
        "responseMode": "responseNode",
        "authentication": "headerAuth"
      }
    },
    {
      "name": "Switch",
      "type": "n8n-nodes-base.switch",
      "position": [500, 300],
      "parameters": {
        "mode": "rules",
        "rules": [
          { "output": "pending", "conditions": { "value1": "{{ $json.status }}", "operation": "equals", "value2": "pending" } },
          { "output": "paid", "conditions": { "value1": "{{ $json.status }}", "operation": "equals", "value2": "paid" } },
          { "output": "shipped", "conditions": { "value1": "{{ $json.status }}", "operation": "equals", "value2": "shipped" } },
          { "output": "cancelled", "conditions": { "value1": "{{ $json.status }}", "operation": "equals", "value2": "cancelled" } }
        ],
        "fallbackOutput": "extra"
      }
    },
    {
      "name": "Notify Warehouse",
      "type": "n8n-nodes-base.slack",
      "position": [750, 200]
    },
    {
      "name": "Send Confirmation",
      "type": "n8n-nodes-base.emailSend",
      "position": [750, 300]
    },
    {
      "name": "Update Tracking",
      "type": "n8n-nodes-base.httpRequest",
      "position": [750, 400]
    },
    {
      "name": "Process Refund",
      "type": "n8n-nodes-base.stripe",
      "position": [750, 500]
    }
  ],
  "connections": {
    "Webhook": { "main": [[{ "node": "Switch", "type": "main", "index": 0 }]] },
    "Switch": {
      "main": [
        [{ "node": "Notify Warehouse", "type": "main", "index": 0 }],
        [{ "node": "Send Confirmation", "type": "main", "index": 0 }],
        [{ "node": "Update Tracking", "type": "main", "index": 0 }],
        [{ "node": "Process Refund", "type": "main", "index": 0 }]
      ]
    }
  }
}

Copie esse JSON e cole no n8n para importá-lo. Não se esqueça de substituir os nós Slack, Email, HTTP Request e Stripe pelas configurações dos seus próprios serviços.

3.5 Testes e entrada em produção

O n8n oferece dois tipos de URL:

• Test URL: usada no desenvolvimento e na depuração; só executa enquanto o teste manual estiver ativo
• Production URL: só funciona depois da ativação e é a URL usada pelo serviço externo

O processo é este:

1. faça uma chamada para a Test URL e observe a ordem de execução dos nós e o fluxo dos dados
2. depois de confirmar que tudo funciona, clique no botão “Active” no canto superior direito
3. informe a Production URL à sua plataforma de e-commerce (ou use o Zapier como intermediário)

Durante os testes, você pode simular a chamada com curl:

curl -X POST https://your-n8n-instance.com/webhook/orders/12345 \
  -H "Content-Type: application/json" \
  -H "X-Shop-Secret: your-secret-key" \
  -d '{"status": "paid", "customer_email": "[email protected]"}'

Se você receber a resposta 200 e encontrar a execução no log, a integração está funcionando.

4. Como evitar problemas em produção

Um workflow funcionar nos testes não significa que ele já esteja pronto para produção. Estes são alguns problemas que encontrei pelo caminho.

4.1 Não relaxe na autenticação

Header Auth é apenas o primeiro passo. Se o sistema que fará as chamadas usa um endereço IP fixo, adicionar uma IP Whitelist deixa tudo mais seguro.

Nas opções avançadas do nó Webhook há o parâmetro “IP Whitelist”. Informe nele a lista dos IPs permitidos. Chamadas de qualquer outro endereço serão recusadas sem sequer acionar o workflow.

JWT Auth também é uma boa opção, embora sua configuração seja um pouco mais complexa. Se você controla o sistema que faz as chamadas, Header Auth + IP Whitelist costuma ser suficiente.

4.2 Os erros precisam chegar a alguém

Se o nó Webhook falhar, quem fez a chamada pode receber apenas um erro 500. Você, porém, precisa saber exatamente o que aconteceu.

A solução é adicionar um nó Error Trigger ao workflow para enviar automaticamente uma notificação pelo Slack quando houver um erro. A configuração é mais ou menos assim:

Error Trigger → Slack (enviar mensagem de erro e ID da execução)

Assim, se algo falhar de madrugada, você verá a notificação no celular, em vez de descobrir o problema pela reclamação de um usuário na manhã seguinte.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

4.3 Uma dica de desempenho

Se o workflow precisar chamar várias APIs externas, como consultar o estoque, enviar e-mails e acessar o serviço de pagamento, a resposta pode demorar. Quem fez a chamada talvez desista quando o tempo limite for atingido.

Nesse caso, use o modo de resposta Immediately: retorne 200 primeiro e continue o processamento em segundo plano. A desvantagem é que o sistema chamador não saberá o resultado final e precisará consultá-lo de outra forma.

É indicado para tarefas agendadas em lote e notificações não críticas. Não é indicado para confirmações de pagamento nem consultas em tempo real.

4.4 Use o log de Executions para depurar

O n8n registra cada execução. Clique em “Executions” no menu à esquerda para ver os dados de entrada e saída de cada chamada, quanto tempo cada nó levou e em qual etapa ocorreu um erro.

Um detalhe: por padrão, o log de execução mantém apenas as 1.000 entradas mais recentes. Se o volume de chamadas for alto, talvez seja necessário ajustar a variável de ambiente EXECUTIONS_DATA_MAX_AGE ou exportar os logs regularmente.

Além disso, os logs da Test URL e da Production URL são exibidos separadamente. Não confunda os dois.

Conclusão

É isso.

O Webhook funciona como uma campainha para o n8n: alguém toca e seu workflow começa a trabalhar. Ao configurá-lo, preste atenção ao HTTP Method e ao Response Mode. Sempre que possível, use parâmetros de rota para não encher a query string de informações.

Como escolher entre IF e Switch? Use IF para duas ramificações e Switch para três ou mais. Evite IFs aninhados: além de difíceis de ler, eles dão trabalho para manter.

Você pode aproveitar diretamente o workflow de processamento de pedidos apresentado aqui; só precisa trocar as configurações do Slack, Email e Stripe. Faça alguns testes com a Test URL e só ative o workflow depois de confirmar que tudo está correto.

Por fim, não economize na segurança. Use Header Auth e, se possível, IP Whitelist. Configure também notificações de erro, ou você pode nem perceber quando algo der errado.

Se tiver alguma dúvida, deixe um comentário ou pesquise diretamente na comunidade do n8n, onde há muita gente experiente disposta a ajudar.