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.

EventoQuando sai
execution.startedLogo depois que a execução é criada.
step.startedQuando uma etapa começa, depois que o módulo foi acionado.
step.finishedQuando uma etapa termina, em completed, failed ou canceled. failed cobre falha técnica e recusa de negócio.
execution.finishedQuando 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"
    }
  ]
}
CampoO que é
event_idIdentificador único do evento. Use para deduplicar.
eventUm dos quatro eventos.
occurred_atMomento da emissão, em UTC.
stepsEtapas 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.

Did this page help you?