O que o Webhook Faz
O nó Webhook no n8n permite que você construa endpoints de API completamente customizados, transformando o n8n em um receptor universal de API que pode receber dados ou eventos de qualquer app, serviço ou script externo.
- Escuta requisições HTTP recebidas (como POST, GET, etc.) em uma URL customizada gerada pelo n8n
- Aciona seu workflow instantaneamente quando dados chegam de outra app, serviço ou script
- Faz o n8n agir como receptor universal de API - qualquer app que pode enviar webhooks ou requisições HTTP pode agora acionar sua lógica de workflow
- Suporta opções chave: caminhos customizados, métodos HTTP, autenticação (opcional, para segurança), URLs de teste/produção
Principais Casos de Uso
- Triggers Instantâneos de Workflow: Reagir a envios de formulário, eventos de CRM/web app, notificações de sistema de pagamento ou dados de IoT
- Construir Endpoints de API: Criar seus próprios microserviços leves ou APIs de automação dentro do n8n, onde clientes enviam dados E recebem respostas estruturadas
- Workarounds de Integração: Quando um app ou serviço não pode usar triggers nativos, simplesmente conecte-o via webhooks
- Receber Notificações: De serviços como GitHub, Stripe, Shopify, ou qualquer sistema que suporte webhooks
- Formulários Web: Processar envios de formulários HTML customizados
Como Configurar
Configuração Básica
- Adicionar Webhook Node: Defina o método HTTP (GET, POST, etc.) e caminho customizado
- Copiar URL: O n8n gera automaticamente uma URL única
- Test URL: Para desenvolvimento e testes
- Production URL: Para uso quando workflow estiver ativo
- Configurar Remetente: Cole a URL do webhook nas configurações de webhook/evento da outra aplicação, ou teste com Postman/cURL
- Modo de Resposta: Escolha como responder:
- Immediately: Responde imediatamente com confirmação simples
- When Last Node Finishes: Responde após workflow completar
- Using 'Respond to Webhook' Node: Para respostas customizadas
- Testar e Iterar: Use URL de teste para debugging ativo, então mude para URL de produção quando live
Opções de Configuração
Métodos HTTP
- GET: Receber dados via query parameters
- POST: Receber dados no body (mais comum)
- PUT: Atualizar recursos
- PATCH: Atualização parcial
- DELETE: Remover recursos
Caminho Customizado
Defina um caminho descritivo para seu webhook:
/form-submission/stripe-payment/github-push- Facilita organização quando tem múltiplos webhooks
Autenticação
Proteja seu webhook com autenticação:
- Header Auth: Requer header específico com token
- Basic Auth: Username e password
- None: Webhook público (cuidado!)
Test vs Production URL
Test URL
- Disponível durante desenvolvimento
- Ativa apenas quando workflow está aberto no editor
- Perfeita para debugging com ferramentas como Postman
- URL muda quando workflow é reaberto
Production URL
- URL permanente e estável
- Ativa apenas quando workflow está ATIVADO
- Use esta URL em integrações reais
- Não muda a menos que você altere o caminho
IMPORTANTE: Sempre teste com Test URL primeiro, depois ative o workflow e mude para Production URL!
Exemplos Práticos
Exemplo 1: Formulário de Contato HTML
Cenário: Processar envios de formulário de site
- Webhook: POST /contact-form
- Formulário HTML: Envia para URL do webhook
- Workflow: Valida dados → Envia email → Salva no banco
- Resposta: "Obrigado! Entraremos em contato."
Exemplo 2: Webhook do Stripe
Cenário: Processar eventos de pagamento
- Webhook: POST /stripe-webhook
- Stripe: Envia evento quando pagamento é concluído
- Workflow: Valida assinatura → Atualiza banco → Envia email de confirmação
- Resposta: Status 200 para confirmar recebimento
Exemplo 3: GitHub Webhook
Cenário: Acionar build quando código é pushed
- Webhook: POST /github-push
- GitHub: Envia evento de push para repositório
- Workflow: Extrai branch → Aciona deploy se branch = main → Notifica equipe
Exemplo 4: API Customizada para Mobile App
Cenário: Endpoint para app mobile enviar dados de usuário
- Webhook: POST /user-data com autenticação
- App: Envia dados do usuário
- Workflow: Valida → Processa → Retorna resposta customizada
- Respond to Webhook: Retorna {"success": true, "userId": 123}
Melhores Práticas
- Sempre teste com Test URL primeiro, mude para production apenas quando pronto
- Adicione autenticação se webhook for exposto publicamente
- Valide dados recebidos antes de processar (use IF node para validação)
- Use caminhos descritivos para facilitar organização e debugging
- Configure resposta apropriada baseado no que cliente espera
- Log requisições para debugging e auditoria
- Trate erros graciosamente - sempre retorne resposta, mesmo em erro
- Documente seus webhooks - quais dados espera, formato de resposta, etc.
Segurança
Considerações Importantes de Segurança
- Nunca exponha webhooks sem autenticação para operações sensíveis
- Valide assinaturas quando plataformas oferecem (como Stripe, GitHub)
- Limite taxa de requisições para prevenir abuso
- Valide origem das requisições quando possível (IP whitelist)
- Não confie cegamente em dados recebidos - sempre valide e sanitize
- Use HTTPS - n8n cloud já fornece, self-hosted deve configurar
- Rotacione tokens de autenticação regularmente
- Log acessos suspeitos para monitoramento de segurança
Debugging de Webhooks
Ferramentas Úteis
- Postman: Testar requisições manualmente
- cURL: Testar via linha de comando
- webhook.site: Ver exatamente o que está sendo enviado
- n8n Execution Log: Inspecionar dados recebidos
Problemas Comuns
- Webhook não aciona: Workflow está ativado? Usando Production URL?
- Dados não aparecem: Verifique formato do body (JSON, form-data, etc.)
- Erro de autenticação: Confirme headers de auth estão corretos
- Timeout: Workflow está levando muito tempo, considere processamento assíncrono
Combinando com Respond to Webhook
Para APIs completas e bidirecionais:
- Configure Webhook com response mode "Using 'Respond to Webhook' Node"
- Adicione sua lógica de processamento
- Termine com Respond to Webhook para enviar resposta customizada
Isso permite criar endpoints de API completos onde você controla totalmente request E response!