Webhook de cancelamento por regra de assinatura
A QI Tech envia este webhook quando uma regra de assinatura do QI Sign reprova a jornada do tomador. A dívida (CCB) é cancelada antes do desembolso. O webhook diz qual regra reprovou e traz o dossiê do signatário, para que você entenda a reprovação sem abrir um chamado.
Os motivos de cancelamento e quem decide cada um estão em Regras de negócio.
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos nos payloads.
Os dois formatos
O formato muda conforme o produto da dívida, e só um deles traz o dossiê:
| Dívida | webhook_type | Traz signers e signed_contract_url |
|---|---|---|
| Consignado privado (originação leilão), previdência privada e cartão consignado | laas.credit_operation.status_change | Sim |
Demais dívidas emitidas pelo POST /debt | debt | Não |
No formato debt, data traz cancel_reason, cancel_reason_enumerator, reason_description e requester_identifier_key. Para ver as evidências de uma dívida nesse formato, fale com o time de suporte da QI Tech.
Corpo do webhook
| Campo | Tipo | Descrição |
|---|---|---|
key | uuid | Chave da dívida (CCB). |
status | string | Sempre canceled. |
webhook_type | string | laas.credit_operation.status_change ou debt. |
event_datetime | string | Data e hora do cancelamento, no formato AAAA-MM-DD HH:MM:SS. |
data | object | O motivo do cancelamento e o dossiê. Veja a tabela abaixo. |
Atributos de data
| Campo | Tipo | Descrição |
|---|---|---|
cancel_reason | string | Texto do motivo. Para reprovação por regra de assinatura: Operação cancelada por regra de assinatura do solicitante. |
cancel_reason_enumerator | string | Código do motivo. Para reprovação por regra de assinatura: rule_analysis_status. |
reason_description | string | A regra de assinatura que reprovou. Veja Valores de reason_description. |
operation_type | string | O tipo da operação. Ex.: structured_operation. Só no formato laas.credit_operation.status_change. |
signed_contract_url | string | O relatório da jornada em PDF, gerado pelo QI Sign. A CCB não foi assinada. Só no formato laas.credit_operation.status_change. |
signers | array | O dossiê de cada signatário. Veja Dossiê do signatário. Só no formato laas.credit_operation.status_change. |
requester_identifier_key | string | O identificador que você enviou na emissão da dívida. Só no formato debt. |
No cancelamento, o dossiê não traz ip_address, similarity_score, biometry_analysis_reference nem images.simplified_dossier. O IP do signatário está em device_data.ip.
As URLs de signed_contract_url e de signers[].images expiram cerca de 24 horas depois do envio do webhook. Baixe e guarde os arquivos ao receber o webhook.
Valores de reason_description
reason_description é o nome da regra de assinatura configurada no QI Sign que reprovou a jornada. A lista depende das regras da sua integração. Valores frequentes:
reason_description | A regra reprovou porque |
|---|---|
face_validation | A validação facial do tomador não atingiu a pontuação mínima. |
ocr_flags | A leitura do documento encontrou um indicador reprovado em document.ocr. |
fraudulent_document | O documento de identificação foi considerado fraudulento. |
Para conferir a reprovação, leia no dossiê o bloco da regra: biometry para face_validation, document.ocr[].document_data para ocr_flags e fraudulent_document.
Exemplo — dívida cancelada por regra de validação facial
O tomador enviou um RG físico e a validação facial reprovou (face_validation.score 3). O dossiê traz os dados extras da jornada (document.ocr e liveness.flags). As URLs assinadas estão encurtadas.
{
"key": "2d7b9e4f-6a1c-4f3e-8b5d-0c9a7e2f1b64",
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2026-11-18 10:40:48",
"data": {
"cancel_reason": "Operação cancelada por regra de assinatura do solicitante",
"cancel_reason_enumerator": "rule_analysis_status",
"reason_description": "face_validation",
"operation_type": "structured_operation",
"signed_contract_url": "https://qisign-dossiers-bucket-production.s3.amazonaws.com/6c1e8a3f-2b9d-4e7a-a5c0-3f8d1b6e9c27.pdf?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"signers": [
{
"id": "e8a2c4f6-9b1d-4e3a-b7c5-2d0f6a8e1c39",
"signer_data": {
"id": "e8a2c4f6-9b1d-4e3a-b7c5-2d0f6a8e1c39",
"name": "MARIA SOUZA",
"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": "+5511999999999",
"birthdate": "1992-12-22",
"document_number": "123.456.789-09",
"document_submission_method": "email",
"authentication_submission_method": "whatsapp"
},
"images": {
"face_image_url": "https://qisign-face-images-bucket-production.s3.amazonaws.com/5a9c1e7b-3d4f-4b2a-9e8c-7f1d0b6a2c53.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_front_url": "https://qisign-personal-documents-bucket-production.s3.amazonaws.com/9d3f7b1e-5c2a-4e8d-a6b4-1e0c8f2d7a95.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_back_url": "https://qisign-personal-documents-bucket-production.s3.amazonaws.com/1b6e4a8c-7f2d-4c9b-8a3e-5d0f9c1b4e72.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_front_template": "rg_front",
"document_back_template": "rg_back"
},
"biometry": {
"face_validation": {
"score": 3,
"provider": "qitech",
"available": true,
"recommendation": "reprove"
},
"fraud_base_flag": false,
"face_validation_score": 3,
"face_validation_available": true
},
"document": {
"template": "rg_front",
"face_match_score": 100,
"ocr": [
{
"file_type": "jpeg",
"template_type": "rg_front",
"document_data": {
"name": "MARIA SOUZA",
"is_copy": false,
"birthdate": "1992-12-22",
"cpf_number": "123.456.789-09",
"has_disability": false,
"place_of_birth": "SAO PAULO-SP",
"expiration_date": "2035-06-24",
"found_state_text": true,
"found_footer_text": true,
"found_header_text": true,
"is_child_document": false,
"all_edges_detected": true,
"cpf_signer_mismatch": false,
"has_physical_damage": false,
"face_tampering_detected": false,
"screen_display_detected": false,
"text_tampering_detected": false,
"found_illeterate_person_text": false,
"has_missing_document_section": false,
"has_textual_legibility_issues": false
}
},
{
"file_type": "jpeg",
"template_type": "rg_back",
"document_data": {
"is_copy": false,
"father_name": "JOSE SOUZA",
"mother_name": "ANA SOUZA",
"issuance_date": "2025-06-24",
"has_disability": false,
"found_side_text": true,
"has_missing_data": false,
"found_footer_text": true,
"all_edges_detected": true,
"has_physical_damage": false,
"screen_display_detected": false,
"text_tampering_detected": false,
"has_missing_document_section": false,
"has_textual_legibility_issues": false
}
}
]
},
"liveness": {
"result": "live",
"flags": {
"multiple_people": false,
"total_execution_time": 29.954
}
},
"device_data": {
"ip": "203.0.113.25",
"model": "iPhone",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.7 Mobile/15E148 Safari/604.1",
"coordinates": [-46.6333, -23.5505]
},
"locations": [],
"link_first_clicked_at": "2026-11-18T00:09:19Z",
"signed_at": "2026-11-18T10:39:58Z"
}
]
}
}
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.