Webhook

Aviso quando o preenchimento do formulário termina

Quando a pessoa termina de preencher, o ClickForm envia um webhook para a URL configurada em callback_url.

Há dois lugares para informar essa URL. As duas podem existir ao mesmo tempo.

  • No formulário, em POST /api/v1/forms. Vale para os runs daquele formulário.
  • No run, em POST /api/v1/versions/{version_key}/runs. É opcional e específico daquela execução. Convive com a URL do formulário. 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 em GET /api/v1/versions/{version_key}/runs/{run_key} e lê o campo responses. Se essa consulta for repetida, o espaçamento está em Integração resiliente. Nessa consulta, context e responses usam a key interna do campo.

O que chega no corpo

O POST vai direto, sem envelope de evento. O corpo traz form_key, version_key, run_key, completed_at e responses. Quando há arquivo, entra também attachments, com a mesma árvore e a object key do arquivo no lugar da URL.

form_key, version_key e run_key são o UUID do formulário, da versão e da execução. A chave dentro de responses e de attachments é a key do campo, ou o external_key quando a Version declara um.

key é o identificador do campo gerado pela API a partir do rótulo, com um sufixo (nome-completo-821962496a9d). Ela vale na tela, no context do Run, na resposta gravada e no GET do Run. Criar ou atualizar a Version gera outra key, com sufixo novo, mesmo no PUT da mesma version_key. O valor enviado no corpo é descartado.

external_key é o nome que você escolhe. No webhook de conclusão, responses e attachments usam esse nome, normalizado para snake_case ("Nome Completo" vira nome_completo). Sem external_key, o webhook usa a key. Na atualização, a external_key gravada é a do corpo: o mesmo valor reenviado permanece; omitida, o campo fica sem ela e o webhook volta para a key recém-gerada.

keyexternal_key
O que éIdentificador do campo, gerado a partir do rótulo, com sufixoNome que você escolhe para o webhook
Onde valeTela, context do Run, resposta gravada e GET do Runresponses e attachments do webhook de conclusão
Se não informarA API geraO webhook usa a key
Na criação ou atualização da VersionA API gera outra, com sufixo novo. O valor enviado é descartadoPermanece se o corpo repetir o mesmo valor. Omitida, o webhook volta para a key nova

O ClickFlow lê essas mesmas chaves de responses no template_mappings. Com external_key reenviada, o mapa continua válido depois da atualização, porque o nome não muda. Sem ela, ou se o corpo deixar de enviá-la, o mapa que apontava para a key anterior deixa de achar a resposta: a Version já tem outra key.

{
  "form_key": "9b2e4f6a-1c3d-5e7f-8091-a2b3c4d5e6f7",
  "version_key": "e4c3d0e8-a6d3-484e-9b00-cdd28232c694",
  "run_key": "cc65ba6a-3ed5-44fb-bd28-e996610d69cd",
  "completed_at": "2026-05-06T12:04:11Z",
  "responses": {
    "customer_full_name": "Maria da Silva",
    "customer_email": "[email protected]"
  }
}

customer_full_name e customer_email são os valores do exemplo de contrato. Um external_key sem caractere válido, repetido no mesmo nível, igual à key interna de outro campo desse nível, ou usado em header, paragraph e na raiz de cep, devolve 400. A raiz e os subcampos de CEP formam um nível. Cada repeater tem o seu.

O passo a passo de criar o formulário e o run está em Primeiros passos do ClickForm. A referência da criação do formulário está em Criar Formulário.

Próximo passo ➡️

  • Webhooks — o webhook de saída do ClickFlow e o dos módulos.
  • Collections — Postman, Insomnia e Bruno prontos para testar o Módulo de Coleta de Dados (ClickForm).
  • FAQ: dúvidas em ClickFlow — respostas curtas para as dúvidas mais comuns.

Did this page help you?