Trigger Flow: disparar pela API e receber webhooks

​

Onde fica no painel

​

Como configurar

​

Disparo genérico: POST /flows/trigger

curl -X POST https://api.zatten.com/api/v1/flows/trigger \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "lead.tag_added",
    "lead_number": "5511999998888",
    "trigger_event": { "tag_id": "8f2a…" },
    "idempotency_key": "crm-evt-01HXYZ"
  }'

{
  "message": "Flows dispatched",
  "trigger_type": "lead.tag_added",
  "matched": 2,
  "dispatched": 1,
  "deduped": false,
  "runs": [
    { "run_id": "9c1e…", "flow_name": "Boas-vindas VIP", "status": "running", "reason": null },
    { "run_id": "4b2f…", "flow_name": "Outro fluxo", "status": "skipped",
      "reason": "tag_id: esperado \"8f2a…\", evento trouxe \"3c1b…\"" }
  ]
}

• matched: fluxos ligados com esse gatilho.
• dispatched: quantos de fato rodaram. Menor que matched não é erro: o reason diz qual filtro do gatilho não bateu.
• deduped: true: a idempotency_key já foi usada nas últimas 24 horas. Nada rodou.

​

Webhook de entrada: POST /hooks/<path>

1. No editor, crie um fluxo com o gatilho Webhook recebido.
2. Preencha o Path (só minúsculas, números e hífen, ex.: erp-pedido-fechado). Ele é único no projeto.
3. Em Campos que você vai receber, declare os campos do JSON que o fluxo vai usar (pedido_id, cliente.nome). Cada um vira {{trigger.body.<campo>}}.
4. Salve, ligue o fluxo e cole a URL no sistema de origem.

curl -X POST "https://api.zatten.com/api/v1/hooks/erp-pedido-fechado?lead_number=5511999998888&idempotency_key=pedido-9182" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{ "pedido_id": 9182, "cliente": { "nome": "Ana" } }'

{ "pedido_id": 9182, "cliente": { "nome": "Ana" } }
{{trigger.body.pedido_id}}     → 9182
{{trigger.body.cliente.nome}}  → Ana

​

Como funciona por trás

• O projeto vem da chave. Uma chave nunca dispara fluxo em outro projeto.
• Cada fluxo ligado com o gatilho é testado contra os filtros. Os que batem viram execuções; os outros ficam como Ignorado.
• A idempotência vale para a combinação gatilho + lead + idempotency_key, por 24 horas. A mesma chave para outro lead ou outro gatilho roda normalmente. Sem idempotency_key, cada chamada roda os fluxos de novo.
• A execução segue na fila, em segundo plano. O 202 quer dizer “recebido e despachado”, não “terminou”.
• As regras de limite da API valem para estas rotas.

​

Pelo MCP

​

Armadilhas

• O corpo precisa ser JSON. Sem Content-Type: application/json, o fluxo roda, mas {{trigger.body}} chega vazio. Remetentes que postam formulário (form-urlencoded) não funcionam direto.
• 202 não quer dizer que rodou. No /hooks, um path errado também responde 202. Confira nas Execuções.
• O lead precisa existir. Webhook de um número que nunca falou com o projeto nem foi importado em Contatos dá 404. Nada roda.
• Um fluxo antigo sem Path responde a qualquer /hooks/… do projeto. Hoje o editor exige o Path; revise fluxos antigos.
• Gatilho em breve não roda pela API. lead.created, lead.message_received, lead.property_changed e lead.inactive são aceitos, mas não há fluxo ligado com eles: matched vem 0.
• A API aceita lead.ai_toggled, mas o editor não tem esse gatilho, então não há fluxo para rodar.
• Nunca ponha a chave de API num front-end público. Quem tem a chave lê e altera os leads do projeto.

​

Perguntas frequentes

​

Para saber mais

• Disparar fluxos e webhook de entrada (API)
• Autenticação, Limites, Erros
• Trigger Flow: catálogo de blocos
• Chaves de API do projeto
• Termos para buscar: “idempotency key”, “webhook de entrada”, “trigger_event”, “x-api-key”.