3.5. Webhooks para acompanhar status
Webhook do ClickFlow e dos módulos
ClickFlow
No disparo da execução, o campo opcional callback_url recebe o webhook de saída. Ele vai no POST /api/v1/flows/{flow_id}/execute do Executor. Sem o campo, a execução segue como antes e nenhum evento é enviado.
{
"channel": "whatsapp",
"contact": {
"phone_number": "5511999999999"
},
"callback_url": "https://api.cliente.com/webhooks/clickflow"
}A URL é conferida no disparo. Se for inválida, a resposta é 400 e a execução não é criada. A URL aceita fica gravada na execução e volta no objeto da execução, no disparo e em GET /api/v1/executions/{execution_id}.
Para testar, use uma URL https pública. Um serviço como webhook.site serve para ver os eventos chegando.
O que a URL precisa ser
São recusadas:
- esquema diferente de
https; - URL sem host;
- usuário e senha na URL (
https://usuario:senha@host); - host que resolve para loopback, rede privada, link-local (incluindo o endereço de metadata de nuvem), endereço não especificado ou multicast.
A mesma conferência acontece de novo no momento do envio. Se o host passar a apontar para um desses endereços, a entrega é recusada.
O endpoint de vocês deve responder em até 10 segundos.
Eventos
São quatro. Cada um sai uma vez.
| Evento | Quando sai |
|---|---|
execution.started | Logo depois que a execução é criada. |
step.started | Quando uma etapa começa, depois que o módulo foi acionado. |
step.finished | Quando uma etapa termina, em completed, failed ou canceled. failed cobre falha técnica e recusa de negócio. |
execution.finished | Quando a execução chega a um estado terminal: completed, failed ou canceled. |
Se a etapa falha no próprio disparo e o link nunca chega a existir, não há step.started. Saem step.finished e, em seguida, execution.finished.
A ordem de chegada não é garantida. Cada aviso diz que algo aconteceu e traz um retrato da execução e das etapas naquele momento. Se o aviso se perder, ele não é reenviado, e a execução não para por isso. Use event_id para ignorar uma entrega repetida. Quando precisar do estado atual, leia execution e steps do próprio aviso. Se steps não vier, consulte o GET.
Não há assinatura neste webhook. Proteja o endpoint com uma URL que só o seu sistema conhece, ou com uma allowlist de origem.
Corpo do aviso
Todo evento tem a mesma forma: metadados da entrega, o objeto execution (mesmo formato de GET /api/v1/executions/{execution_id}) e steps (mesmo formato de GET /api/v1/executions/{execution_id}/steps).
{
"event_id": "01JABCXYZ",
"event": "step.started",
"occurred_at": "2026-09-28T12:00:01.123456789Z",
"execution": {
"execution_id": "exec-123",
"flow_id": "flow-abc",
"account": { "id": 42, "key": "acct-uuid", "name": "Acme" },
"status": "running",
"channel": "api",
"contact": { "phone_number": "5511999999999" },
"context": { "external_ref": "pedido-987" },
"callback_url": "https://api.cliente.com/webhooks/clickflow",
"current_step": {
"id": "2",
"type": "form",
"url": "https://forms.exemplo.com/r/abc123"
},
"created_at": "2026-09-28T12:00:00Z",
"updated_at": "2026-09-28T12:00:01Z"
},
"steps": [
{
"step_id": "2",
"attribute_type": "form",
"status": "running",
"started_at": "2026-09-28T12:00:00Z",
"updated_at": "2026-09-28T12:00:01Z"
}
]
}| Campo | O que é |
|---|---|
event_id | Identificador único do evento. Use para deduplicar. |
event | Um dos quatro eventos. |
occurred_at | Momento da emissão, em UTC. |
steps | Etapas no mesmo formato do GET de steps. |
O execution acompanha o GET da execução. Campo novo nesse GET passa a aparecer aqui também. steps acompanha o GET das etapas. steps: [] significa que a execução ainda não tem etapa. Se steps não vier, a leitura das etapas falhou e o evento chega mesmo assim; consulte o GET para o detalhe, inclusive anexos do formulário em link temporário de leitura. O context de uma etapa pode trazer dados pessoais, como respostas de formulário e, na etapa de assinatura, IP e geolocalização em signature_callback.signer.
current_step só aparece quando o canal é api ou web e há uma etapa em andamento. No canal whatsapp ele não vem: o Executor já entrega o link ao contato. Em execução terminada ele também não vem. url fica null em etapa sem link público, como acceptance. web_url só vem quando o canal é web.
O passo do disparo está em Primeiros passos do ClickFlow. A referência está em Inicia uma execução de fluxo.
Módulos
Coleta de Dados (ClickForm)
Quando a pessoa termina de preencher o formulário, o Módulo de Coleta de Dados (ClickForm) envia um webhook para a URL informada em callback_url. A URL pode ficar no formulário, valendo para todos os runs, e também no run, só para aquela execução. Se as duas URLs forem diferentes, as duas recebem o aviso. Se forem iguais, ignorando espaços nas pontas, a API envia um único POST. Quem não quiser webhook consulta o run e lê o campo responses.
O detalhe está em Webhook do Módulo de Coleta de Dados (ClickForm).
Aceite e Notificação
Quando um aceite atinge um status final, o módulo envia um recibo por POST na webhook_url informada na criação. Se a URL não for informada, o histórico continua disponível por consulta.
O detalhe está em Webhooks e relatórios.
Próximo passo ➡️
- Collections — Postman, Insomnia e Bruno prontos para testar o ClickFlow, o Módulo de Coleta de Dados (ClickForm) e os Módulos de Aceite e de Notificação.
- FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.
Updated 13 days ago