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 únicoPOST.
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.
key | external_key | |
|---|---|---|
| O que é | Identificador do campo, gerado a partir do rótulo, com sufixo | Nome que você escolhe para o webhook |
| Onde vale | Tela, context do Run, resposta gravada e GET do Run | responses e attachments do webhook de conclusão |
| Se não informar | A API gera | O webhook usa a key |
| Na criação ou atualização da Version | A API gera outra, com sufixo novo. O valor enviado é descartado | Permanece 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.
Updated 13 days ago