Asset Webhooks
Throughout the assignment flow, the system sends webhooks to notify the integrating partner about status changes of individual assets. There are two webhook types: trade_receivables.asset_status_change for status changes and trade_receivables.asset_creation to confirm asset creation.
To receive webhooks, you must have a callback URL configured with QI Tech. The configuration defines which statuses you receive: only the events subscribed in it are sent. The creation webhook (asset_creation) is sent to whoever subscribes to the pending_eligibility status. Contact integracao.dtvm@qitech.com.br to set it up. Delivery, retries and signature: see Receiving Webhooks.
Asset status flow
The asset enters pending_eligibility as soon as it is inserted into the batch and, from the eligibility analysis onward, follows one of the paths below. The diagram shows the main path; the full list of statuses is in Asset status enumerators.
Reading the diagram: blue = intermediate status · green = asset assigned and added to the portfolio · red = final denial or discard status.
Webhook structure
All asset webhooks share the same base structure:
| Field | Type | Description |
|---|---|---|
webhook_type | string | Webhook type: trade_receivables.asset_status_change or trade_receivables.asset_creation. |
webhook_datetime | string | Date and time of sending, in the YYYY-MM-DDTHH:MM:SSZ format. |
data | object | Event data. See table below. |
data attributes
| Field | Type | Description |
|---|---|---|
assignment_external_id | string | The external_id of the batch the asset belongs to. |
asset_external_id | string | The external_id of the asset. |
asset_new_status | string | New asset status. |
assignment_configuration_key | string | Identifier of the assignment configuration the batch belongs to — the same key used in the endpoint URLs. |
fund_class_key | string | Identifier of the fund class associated with the batch. |
operation_type | string | Operation type of the assignment configuration (e.g., unsecured_credit, duplicata_mercantil). |
asset_payload | object | Present only in the creation webhook (asset_creation). Contains the asset data as submitted at creation, with purchase_irr calculated inside credit_operation (CCB) or contract (contracts). |
denial_reason | string | Present in denied and registry_denied: source of the denial (the denied_by values). |
denial_metadata | object | Present in denied and registry_denied when there is detail — for example, the eligibility rules that failed or the reason given when removing the asset. |
assignment_configuration_key meansThe assignment configuration is the agreement already registered between the assignor and the fund: it defines which fund the receivables are assigned to, which asset type is accepted, and under which rules the operation runs. It is the same key you already use in the assignment endpoint URLs, obtained during Assignor Onboarding.
Because a single assignor can have more than one active configuration at the same time, this field tells you which agreement the asset is being assigned under. That way you route the webhook to the right flow without calling the API to find out where the asset came from.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "STATUS",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Events by status
Asset Created
Sent when an asset is successfully inserted into the batch. This webhook includes the asset_payload field with all credit operation data submitted at creation. The webhook type is trade_receivables.asset_creation.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_eligibility",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit",
"asset_payload": {
"premiums": [
{
"total_value": 1.2,
"premium_type": "spread"
}
],
"asset_type": "ccb",
"credit_operation": {
"delay": {
"fine": {
"amount": 0.0,
"fine_type": "percentage"
},
"interest": {
"method": "compound",
"pre_fixed": {
"monthly_rate": 0.0,
"calendar_base": "workdays"
}
}
},
"borrower": {
"name": "João Pereira",
"email": "exemplo3@gmail.com",
"phone": {
"number": "948386674",
"area_code": "11"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "84",
"street": "RUA GILBERTO SABINO",
"country": "BRA",
"postal_code": "05425-020",
"neighborhood": "Pinheiros"
},
"person_type": "natural_person",
"natural_person": {
"birthdate": "1970-02-18",
"mother_name": "Natalia Nascimento"
},
"document_number": "969.698.790-03"
},
"contract": {
"cet": 0.0314,
"number": "0032226586/NNT",
"iof_value": 3.04,
"issue_date": "2024-04-24",
"issue_value": 93.05,
"signature_date": "2024-04-24",
"disbursement_date": "2024-04-24",
"disbursement_value": 62.1
},
"pre_fixed": {
"monthly_rate": 0.0179,
"calendar_base": "calendar_365"
},
"external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"installments": [
{
"face_value": 30.81,
"maturity_date": "2025-02-01",
"installment_number": 1
},
{
"face_value": 26.19,
"maturity_date": "2026-02-01",
"installment_number": 2
},
{
"face_value": 29.68,
"maturity_date": "2027-02-01",
"installment_number": 3
},
{
"face_value": 23.74,
"maturity_date": "2028-02-01",
"installment_number": 4
},
{
"face_value": 28.49,
"maturity_date": "2029-02-01",
"installment_number": 5
},
{
"face_value": 19.94,
"maturity_date": "2030-02-01",
"installment_number": 6
},
{
"face_value": 13.96,
"maturity_date": "2031-02-01",
"installment_number": 7
},
{
"face_value": 13.03,
"maturity_date": "2032-02-01",
"installment_number": 8
}
],
"principal_value": 93.05,
"amortization_type": "price",
"interest_rate_type": "pre_fixed",
"originator_document_number": "22.333.444/0001-81"
},
"total_purchase_value": 94.86
}
},
"webhook_type": "trade_receivables.asset_creation",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Approved in Eligibility — Pending Documentation
Sent when the asset is approved in the eligibility analysis and the assignment configuration requires documents (duplicata mercantil and CT-e always go through this status). Submit the required documentation through Document Insertion, if you have not already done so.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_documentation",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pre-Approved
Sent when the asset is pre-approved, after successful document validation (or when no additional documentation is required). The asset is ready to advance to the formalization/registration step.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pre_approved",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pending Registry
Sent when the pre-approved asset is forwarded to the registry. It only happens in assignment configurations whose registry_type requires registration — internal_registry, external_registry, registry_transfer or unfit. The asset stays in this status until the registry responds.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_registry",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Pending Formalization
Status in which the asset has been formalized (registered, when the configuration requires registration) and is able to proceed in the batch until it is added to the portfolio. This transition currently does not send a webhook, even if the status is subscribed. Track it through the asset query or through the batch waiting_assets_to_formalize webhook, in batch webhooks.
Asset Completed
Sent when the asset has been successfully added to the fund's portfolio. This is the final status of a successful asset — from this point on, the asset is within the fund's inventory.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "completed",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Denied in Eligibility
Sent when the asset is denied — in eligibility, in document validation or in invoice validation — or removed from the batch. The webhook carries denial_reason and, when available, denial_metadata. An asset denied because of a document returns to pending_documentation if you submit a new document.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Registry Denied
Sent when the registry denies the asset registration. The asset does not proceed to formalization nor to portfolio inclusion; when the batch is approved, it moves to denied. The webhook carries denial_reason and, when available, denial_metadata; the detail also appears in the asset query.
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "registry_denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Asset Discarded
Status of an asset discarded together with the batch — for example, at the fund's accounting close. After the Assignment Term is signed, the batch's denied assets (denied) also move to discarded. This transition currently does not send an asset webhook, even if the status is subscribed. Track it through the asset query; the batch discard is notified by the discarded webhook in batch webhooks. To take an asset out of the batch, use asset removal, which moves the asset to denied.