Webhooks - Emissão Crédito Clean

Resumo

Após a resposta de sucesso da emissão, você receberá webhooks notificando sobre os eventos do ciclo de vida da operação: assinatura do contrato, desembolso e, eventualmente, cancelamento.

Atenção!

Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.

Webhook de Assinatura

Este webhook é enviado quando o contrato (CCB) é assinado com sucesso.

WEBHOOK_TYPE

debt

STATUS

signature_finished

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:09:33Z",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf"
}

Campos do Webhook de Assinatura

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: signature_finished
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
signed_contract_url	string	URL do contrato assinado (PDF)

Webhook de Desembolso

Este webhook confirma que o desembolso foi realizado com sucesso.

WEBHOOK_TYPE

debt

STATUS

disbursed

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "installments": [
            {
                "due_date": "2025-11-27",
                "total_amount": 87.43,
                "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
                "pre_fixed_amount": 29.26477451,
                "installment_number": 1,
                "principal_amortization_amount": 58.16522549
            },
            {
                "due_date": "2025-12-27",
                "total_amount": 87.43,
                "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
                "pre_fixed_amount": 20.11446867,
                "installment_number": 2,
                "principal_amortization_amount": 67.31553133
            },
            {
                "due_date": "2026-01-27",
                "total_amount": 87.43,
                "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
                "pre_fixed_amount": 11.07075682,
                "installment_number": 3,
                "principal_amortization_amount": 76.35924318
            }
        ],
        "ted_receipt_list": [],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:10:21Z"
}

Campos do Webhook de Desembolso

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: disbursed
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
data.installments	array	Lista de parcelas com suas chaves e valores
data.ted_receipt_list	array	Lista de comprovantes de TED (quando aplicável)

Webhook de Cancelamento

Se a dívida falhar no desembolso ou for devolvida, você receberá um webhook de cancelamento.

WEBHOOK_TYPE

debt

STATUS

canceled

Webhook Body

{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}

Campos do Webhook de Cancelamento

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: canceled
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
data.cancel_reason	string	Descrição textual do motivo do cancelamento
data.cancel_reason_enumerator	string	Enumerador do motivo do cancelamento

Enumeradores de Cancelamento

Enumerador	Descrição
disbursing_error	Operação cancelada por erro durante o desembolso
waiting_signature	Operação cancelada por falta de assinatura
pix_max_retry	Operação cancelada porque o banco receptor não processou o desembolso
manual	Operação cancelada manualmente
agencia_conta_invalida	Agência ou número de conta do destinatário inválidos
invalid_account	Número da conta de destino inexistente ou inválido
invalid_document_number	CPF/CNPJ da conta de destino incorreto
unsupported_transaction	A conta de destino não suporta este tipo de transação
invalid_ispb	O número ISPB é inválido ou inexistente
rejected_payment	Ordem de pagamento rejeitada pelo banco receptor
refund_after_payee_request	Estorno solicitado pelo beneficiário
blocked_account	A conta de destino está bloqueada
amount_too_great	Valor excede o limite da conta de destino
receiver_error	Transação interrompida por erro no PSP do receptor
closed_account	A conta de destino está encerrada
disbursing_hour_closed	Desembolso fora do horário permitido
unregistered_pix_key	A chave Pix não está registrada
spi_timeout	Timeout no controle SPI

---

Webhook de Quitação

Quando todas as parcelas são pagas e a operação é quitada integralmente, o sistema envia este webhook.

WEBHOOK_TYPE

debt

STATUS

settled

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "settlement_amount": 3429.38
    },
    "status": "settled",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T07:03:49Z"
}

Campos do Webhook de Quitação

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: settled
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento
data.settlement_amount	float	Valor total liquidado

Webhook de Confirmação de Cessão

Este webhook é enviado quando uma cessão de operações de crédito é processada. Ele notifica que o processo de cessão foi iniciado e fornece os metadados necessários para rastreamento.

WEBHOOK_TYPE

assignment.status_change

Webhook Body

{
    "key": "b866dc02-73db-42a4-bc66-866d465cbb73",
    "webhook_type": "assignment.status_change",
    "event_datetime": "2026-04-10T22:37:52Z",
    "data": {
        "assignment_key": "550e8400-e29b-41d4-a716-446655440000",
        "term_of_assignment_url": "https://example.com/terms/cessao.pdf",
        "number_of_items": 1,
        "total_amount": 1000,
        "reference_date": "2026-04-10"
    }
}

Campos do Webhook de Confirmação de Cessão

Campo	Tipo	Descrição
key	string	Chave única da cessão
webhook_type	string	Tipo do webhook: assignment.status_change
event_datetime	string	Data e hora do evento
data.assignment_key	string	Identificador único da cessão (UUID)
data.term_of_assignment_url	string	URL para download do Termo de Cessão (PDF)
data.number_of_items	integer	Total de operações de crédito incluídas na cessão
data.total_amount	float	Soma do valor presente de todos os itens da cessão
data.reference_date	string	Data base utilizada nos cálculos da cessão (YYYY-MM-DD)

---

Webhook de Cancelamento Permanente

Operações com status canceled são automaticamente canceladas de forma permanente após 7 dias. O cancelamento permanente também pode ser acionado manualmente via endpoint /debt/{debt_key}/cancel_permanently.

WEBHOOK_TYPE

debt

STATUS

canceled_permanently

Webhook Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {},
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T03:46:31Z"
}

Campos do Webhook de Cancelamento Permanente

Campo	Tipo	Descrição
key	string	Chave única da dívida (DEBT-KEY)
status	string	Status do evento: canceled_permanently
webhook_type	string	Tipo do webhook: debt
event_datetime	string	Data e hora do evento

---

Webhook de Atualização de Parcela

Enviado quando o status de uma parcela é atualizado (pagamento, vencimento, antecipação, etc.).

WEBHOOK_TYPE

installment.status_change

Documentação completa

Payload detalhado e todos os status possíveis estão em Webhooks de Parcelas.

Status de parcela

Status	Descrição
opened	Parcela em aberto
paid	Parcela paga
waiting_payment	Aguardando pagamento
paid_early	Parcela paga antecipadamente
paid_partial	Parcela paga parcialmente
overdue	Parcela vencida
paid_partial_overdue	Parcela paga parcialmente após vencimento
paid_overdue	Parcela paga após vencimento