Gatilho Webhook

O nó Webhook (webhook_trigger) inicia um workflow quando um sistema externo envia uma requisição HTTP para a URL do seu workflow. É o principal ponto de integração para plataformas de e-commerce, construtores de formulários, gateways de pagamento, Zapier, n8n, Make e backends personalizados.

Abra Automações → editor do workflow → seção da paleta Triggers → arraste Webhook para o canvas.

Figura 1: Gatilho Webhook — URL, chave de acesso e opções de sincronização

O que ele faz

Quando uma requisição atinge a URL do webhook e o workflow está ativado, o WhatsWave enfileira (ou executa de forma síncrona) uma execução. O contexto HTTP completo torna-se o payload do gatilho para os nós seguintes.

Configuração — passo a passo

1. Adicionar o nó Webhook

1. Crie ou abra um workflow em Automações.
2. No grupo Triggers da paleta, arraste Webhook para o canvas.
3. Conecte-o ao primeiro nó de ação (mensagem, condição, requisição HTTP, etc.).
4. Todo workflow precisa de pelo menos um nó de gatilho — Webhook é o padrão para novos workflows.

2. Copiar URL e chave de acesso

1. Clique no nó Webhook para abrir o diálogo de configuração.
2. Em Execution URL, copie a URL completa:
   • Formato: https://service.whatswave.com.br/wf/{workflow_id}
   • O {workflow_id} é o UUID do seu workflow (visível na URL do editor).
3. Em Access key, copie a chave do webhook:
   • Use Copy sem revelar a chave, ou clique no ícone de olho para exibi-la.
   • A chave não é copiada quando você clona um workflow — gere ou revele novamente na cópia.

3. Configurar opções

O modo síncrono acrescenta ?wait=true à URL de execução automaticamente. Você também pode enviar o header X-Workflow-Wait: true ou o parâmetro de query wait=true.

4. Configurar o sistema externo

No aplicativo que envia (Zapier, sua API, fluxo Shopify, etc.):

1. Defina o método como POST (recomendado para corpos JSON).
2. Cole a Execution URL (com ?wait=true apenas se o modo síncrono estiver ativado).
3. Adicione o header de autenticação:
   • X-Webhook-Key: <your-key>, ou
   • Authorization: Bearer <your-key>
4. Envie Content-Type: application/json ao postar JSON.
5. Envie uma requisição de teste e verifique a execução no Execution history.

Exemplo de requisição:

curl -X POST "https://service.whatswave.com.br/wf/YOUR_WORKFLOW_ID" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Key: YOUR_WEBHOOK_KEY" \
  -d '{
    "phone": "5511999999999",
    "name": "Maria",
    "order_id": "ORD-8842",
    "total": 199.90
  }'

5. Usar dados do gatilho no fluxo

Referencie campos da requisição recebida:

Padrão típico: adicione um nó Variable logo após o gatilho para normalizar telefone e nome antes dos nós Send message ou CRM.

6. Salvar e ativar

1. Save o workflow.
2. Ative o toggle Active — webhooks só disparam quando o workflow está ativado.
3. Execute um teste real a partir do sistema externo (não apenas o teste no editor).

Modo síncrono e nó Return

Use o modo síncrono quando quem chama precisa receber um corpo de resposta imediatamente (ex.: confirmação de formulário, callback de API).

1. Ative Sync mode no nó Webhook.
2. Adicione um nó Return (grupo Logic) no final do ramo com o qual deseja responder.
3. Defina o payload JSON no nó Return.
4. A resposta HTTP inclui:

{
  "success": true,
  "execution_id": "uuid",
  "execution_time_ms": 1234,
  "data": { }
}

data espelha a saída do nó Return. Em caso de falha ou timeout, success é false e error pode estar presente.

Timeout síncrono padrão: 120 segundos (WORKFLOW_WEBHOOK_SYNC_TIMEOUT_MS). Fluxos longos devem permanecer assíncronos.

Modo assíncrono (padrão)

Sem ?wait=true, a API responde imediatamente:

{
  "success": true,
  "message": "Workflow enqueued for execution",
  "job_id": "uuid"
}

Status HTTP 202 Accepted. Acompanhe o progresso no Execution history dentro do editor.

Referência técnica

Endpoint

Payload do gatilho (interno)

O engine armazena esta estrutura em context.trigger:

{
  "body": { },
  "query": { },
  "method": "POST",
  "headers": { }
}

Requisições GET têm body vazio; os parâmetros chegam em query.

Workflows com múltiplos gatilhos

Um workflow pode incluir nós Webhook, Schedule e Manual ao mesmo tempo. Ao salvar, deriva triggers_enabled:

{
  "webhook": true,
  "manual": true,
  "cron": false
}

Cada origem executa o nó de gatilho correspondente (webhook_trigger para HTTP, etc.).

Tipos de gatilho relacionados (fora da paleta)

Dicas e boas práticas

• Números de telefone: sempre inclua o código do país (5511...) nos payloads do webhook antes dos nós Send message.
• Idempotência: sistemas externos podem reenviar webhooks — use um nó Condition ou armazenamento externo para deduplicar por order_id ou id do evento.
• Segredos: nunca exponha a URL + chave em JavaScript no client-side ou em repositórios públicos; rotacione as chaves se vazarem.
• Testes: use o gatilho Manual + payload de teste no editor antes de conectar o tráfego de produção.
• Corpos grandes: prefira referenciar campos específicos ({{trigger.body.items[0].sku}}) em vez de registrar o corpo completo.
• GET para gatilhos simples: integrações só com query podem usar GET com ?phone=5511... — os dados vão para {{trigger.query}}.
• Erros 401: verifique o nome do header da chave e se o workflow está active.

Exemplos de casos de uso

Novo pedido → confirmação no WhatsApp

1. O gatilho Webhook recebe o payload de pedido Shopify/order.
2. Nó Variable: phone ← {{trigger.body.customer.phone}}, name ← {{trigger.body.customer.name}}.
3. Send message: "Hi {{variables.name}}, we received order #{{trigger.body.order_id}}."
4. Nó CRM: criar card na coluna "New orders".

Formulário de lead → qualificar e atribuir

1. Typeform/Zapier faz POST de email, phone, interest.
2. Condition: interest igual a "Enterprise" → ramo A (notificar Slack de vendas via HTTP); senão ramo B (sequência de nutrição).
3. Nó Contact: upsert de contato com tags de {{trigger.body.utm_campaign}}.

Webhook de pagamento (estilo Stripe)

1. O webhook recebe event + data.object.
2. Condition em {{trigger.body.type}} === checkout.session.completed.
3. Send message com link de pagamento ou recibo; nó Return com { "received": true } se o modo síncrono estiver ativado.

FAQ

O webhook funciona com o workflow inativo?
Não. Workflows desativados retornam erro e não enfileiram execuções.

Posso usar a mesma URL para vários workflows?
Não. Cada workflow tem uma URL /wf/{id} única vinculada ao seu UUID.

Qual método HTTP devo usar?
POST para corpos JSON. GET funciona quando você só precisa de parâmetros de query.

Por que {{trigger.headers}} está vazio?
Ative Include headers in output na configuração do nó Webhook.

O que acontece se não existir nó Return no modo síncrono?
A resposta ainda retorna execution_id e metadados de tempo; data é omitido.

Posso desativar a chave de acesso?
Desativar Include headers in output define include_headers: 'false', o que desativa a validação da chave e limpa {{trigger.headers}}. Prefira manter a autenticação ativada para integrações de produção.

Qual a velocidade de entrega?
O modo assíncrono responde em milissegundos; a execução começa via fila de jobs. O modo síncrono bloqueia até o workflow concluir ou atingir o timeout.

Existe limitação de taxa?
Tráfego intenso deve ser suavizado na origem; monitore o histórico de execuções para falhas e considere um design amigável à fila (assíncrono + Return via callback separado, se necessário).

Artigos relacionados

• Visão geral dos gatilhos — todos os tipos de gatilho
• Gatilho Schedule — execuções baseadas em tempo
• Gatilho Manual — testes e execuções sob demanda
• Guia de webhooks recebidos — passo a passo de integração
• Variáveis no workflow — {{trigger.*}} e mais
• Nó Return — respostas HTTP síncronas
• Integração Zapier · Integração n8n