Webhooks de acompanhamento do QI Sign
Enquanto o tomador está na jornada de assinatura do QI Sign, a QI Tech pode enviar webhooks que mostram onde ele está: quando abre o link, quando conclui uma etapa e quando abandona a jornada. Use-os para retomar o contato com um tomador que parou no meio da jornada.
Estes webhooks não mudam o status da dívida. O resultado da formalização chega no webhook de assinatura ou no webhook de cancelamento.
Os webhooks de acompanhamento são opcionais. Para recebê-los, peça ao time de suporte da QI Tech a habilitação do evento document.signer.status_change na sua integração. A URL é a mesma dos demais webhooks; veja Configurando webhooks.
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos nos payloads.
Quando ele chega
data.type | Quando é enviado |
|---|---|
signer_link_clicked | O tomador abriu o link e iniciou a jornada. |
signer_step_completed | O tomador concluiu uma etapa que envia webhook. Hoje é a etapa enrich_personal_data, com os dados que ele informou. |
signer_step_abandoned | O tomador abandonou a jornada. next_signer_signature_step diz em que etapa ele parou. |
Etapas da jornada
Os campos completed_signer_signature_step e next_signer_signature_step usam os nomes das etapas. A ordem e as etapas presentes dependem da configuração da sua jornada.
| Etapa | O que o tomador faz |
|---|---|
resume_operation | Lê o resumo da operação (valores, parcelas, taxas). |
device_scan | Libera o acesso ao dispositivo (câmera e localização). |
face_recognition | Tira a selfie com prova de vida. |
personal_document | Envia o documento de identificação. |
enrich_personal_data | Informa ou confirma dados pessoais (e-mail, telefone, endereço, chave Pix). |
Quando o tomador abandona antes de concluir a primeira etapa, completed_signer_signature_step não vem no webhook.
Corpo do webhook
| Campo | Tipo | Descrição |
|---|---|---|
key | uuid | Chave do envelope de assinatura no QI Sign. Não é a chave da dívida: use data.credit_operation_key. |
status | string | Status do signatário na assinatura. Sempre on_signature. |
webhook_type | string | Sempre document.signer.status_change. |
event_datetime | string | Data e hora do evento, no formato AAAA-MM-DDTHH:MM:SS. |
data | object | O signatário e o evento. Veja a tabela abaixo. |
Atributos de data
| Campo | Tipo | Descrição |
|---|---|---|
id | uuid | Chave do signatário no QI Sign. |
type | string | O evento: signer_link_clicked, signer_step_completed ou signer_step_abandoned. |
name | string | Nome do signatário. |
email | string | E-mail do signatário. Pode ser null. |
status | string | Status do signatário na assinatura. Sempre on_signature. |
document_number | string | CPF do signatário, com máscara. |
credit_operation_key | uuid | Chave da dívida (CCB). Use este campo para ligar o evento à dívida. |
completed_signer_signature_step | string | Última etapa concluída. Presente em signer_step_completed e em signer_step_abandoned. |
next_signer_signature_step | string | Etapa em que o tomador parou. Presente só em signer_step_abandoned. |
enrich_personal_data | object | Dados informados na etapa enrich_personal_data. Presente em signer_step_completed dessa etapa. |
phone | object | Telefone do signatário. Presente em signer_step_abandoned. |
address | object | Endereço do signatário. Presente em signer_step_abandoned quando o tomador já o informou. |
pix_key | string | Chave Pix do signatário. Presente em signer_step_abandoned quando o tomador já a informou. |
Atributos de enrich_personal_data
| Campo | Tipo | Descrição |
|---|---|---|
email | string | E-mail do signatário. |
phone | object | Telefone. Veja Atributos de phone. |
address | object | Endereço. Veja Atributos de address. |
pix_key | string | Chave Pix do signatário. |
Atributos de phone
| Campo | Tipo | Descrição |
|---|---|---|
number | string | Número do telefone, sem DDD. |
area_code | string | DDD. |
international_dial_code | string | Código do país. Ex.: 55. |
Atributos de address
| Campo | Tipo | Descrição |
|---|---|---|
uf | string | Sigla do estado. |
city | string | Cidade. |
street | string | Logradouro. |
number | string | Número. |
complement | string | Complemento. Pode não vir. |
neighborhood | string | Bairro. |
postal_code | string | CEP, com máscara. |
Exemplos
- Link aberto
- Etapa concluída
- Jornada abandonada
{
"key": "e299f7c2-03fa-4ea9-a2bc-e1a4e44440ac",
"data": {
"id": "d1c37283-8ac0-4aaf-9ffe-0f0071d401b9",
"name": "JOAO DA SILVA",
"type": "signer_link_clicked",
"email": null,
"status": "on_signature",
"document_number": "969.698.790-03",
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962"
},
"status": "on_signature",
"webhook_type": "document.signer.status_change",
"event_datetime": "2026-10-02T16:25:02"
}
{
"key": "eed08ea1-a187-4e0f-9535-134c3683b6f8",
"data": {
"id": "d648f566-aa8b-4a64-88db-d29311a2eab8",
"name": "MARIA SOUZA",
"type": "signer_step_completed",
"email": "maria.souza@exemplo.com",
"status": "on_signature",
"document_number": "123.456.789-09",
"credit_operation_key": "0c6f1b2e-7d4a-4f1b-9a3e-5c8d2e7f1a90",
"enrich_personal_data": {
"email": "maria.souza@exemplo.com",
"phone": {
"number": "999999999",
"area_code": "11",
"international_dial_code": "55"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "100",
"street": "Rua Exemplo",
"postal_code": "01000-000",
"neighborhood": "Centro"
},
"pix_key": "12345678909"
},
"completed_signer_signature_step": "enrich_personal_data"
},
"status": "on_signature",
"webhook_type": "document.signer.status_change",
"event_datetime": "2026-10-02T18:35:39"
}
{
"key": "e7ef9e1a-d5c8-46c8-9b7e-32ca4f67a9fa",
"data": {
"id": "262f0f2c-0220-41f7-8189-aae098e98580",
"name": "MARIA SOUZA",
"type": "signer_step_abandoned",
"email": "maria.souza@exemplo.com",
"phone": {
"number": "999999999",
"area_code": "11",
"international_dial_code": "55"
},
"status": "on_signature",
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "100",
"street": "Rua Exemplo",
"complement": "Casa 1",
"postal_code": "01000-000",
"neighborhood": "Centro"
},
"pix_key": "12345678909",
"document_number": "123.456.789-09",
"credit_operation_key": "3d9a7c51-2b8e-4f60-a1d4-6e0b9c3f7a28",
"next_signer_signature_step": "face_recognition",
"completed_signer_signature_step": "device_scan"
},
"status": "on_signature",
"webhook_type": "document.signer.status_change",
"event_datetime": "2026-10-02T19:05:50"
}
Erros
Este webhook não devolve erro ao originador. A sua URL deve responder com um status 2xx em até 5 segundos. O comportamento de entrega e o reenvio estão em Configurando webhooks e Reenvio de notificações.