Delivery Webhook
Overview
Whenever a report delivery is completed, QI CTVM can notify your application by webhook. The notification says which delivery finished, to which destination, and which files it carried — with the status of each report. It is the signal for you to trigger the collection on the SFTP instead of scanning the folder at fixed intervals.
The webhook is optional and configured per delivery routine. Without configuration, no notification is sent.
Tell the integration team the URL that will receive the notifications. We return a Signature Key for you to validate the signature, and we link the configuration to the fund's delivery routine. Enabling is per routine — a fund with two routines configures both.
When it is sent
One notification per completed destination, at the moment that destination finishes being processed.
A destination is only processed after all the reports of the delivery reach a final state — generated or failed. Only then are the files transferred and the notification sent. That is: when the webhook arrives, the folder already has the files.
| Situation | Destination status | Webhook |
|---|---|---|
| All the reports generated | delivered | sent |
| Part of the reports failed | delivered | sent — the ones that failed appear in reports, but have no file in the folder |
| All the reports failed | failed | sent — no file is transferred |
A routine that delivers eight reports to an SFTP folder generates one notification, with eight entries in reports. There is no notification per file.
If the same delivery has two destinations — for example an SFTP folder and an e-mail — there are two notifications, one per destination, and both carry the same list of reports.
The notification of a destination is recorded when it is sent and is not repeated. A reprocessing of the sending does not generate a new notification. To resend a notification that has already been issued, see Receiving Webhooks.
Webhook types
webhook_type | When |
|---|---|
report.recurring_delivery_destination_completed | Delivery originated from a routine — the case of the fund's daily report delivery. |
report.delivery_destination_completed | One-off delivery, created outside the routine. |
The payload difference is in data: the routine type adds recurring_delivery_key and description.
Webhook structure
{
"webhook_type": "report.recurring_delivery_destination_completed",
"webhook_datetime": "2026-07-30T09:12:44Z",
"data": {
"solicitation_time": "2026-07-30T09:05:00Z",
"delivery_key": "3f1c9b7e-0a44-4c21-9f18-6b2d5e7a1c33",
"recurring_delivery_key": "b8d2a6f4-77c1-4e90-8a3b-1d5f9c0e2a77",
"description": "Relatórios diários — FUNDO EXEMPLO FIDC",
"destination": {
"destination_key": "c4e7a1b9-2d63-4f85-90ab-7c1e3f5d8b02",
"destination_type": "sftp",
"folder_path": "/fundos/fundo_exemplo",
"status": "delivered"
},
"reports": [
{
"report_type": "consolidated_credit_rights_acquisition_assets",
"file_name": "example_name_consolidated_credit_rights_acquisition_assets_2026-07-29.csv",
"fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
"reference_date": "2026-07-29",
"status": "generated"
},
{
"report_type": "cash_account_demonstrative",
"file_name": "example_name_cash_account_demonstrative_2026-07-29.xlsx",
"fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
"reference_date": "2026-07-29",
"status": "generated"
}
]
}
}
data attributes
| Field | Type | Description |
|---|---|---|
solicitation_time | string | Date and time the delivery was requested, in ISO 8601 (UTC). |
delivery_key | string | Identifier of the delivery (UUID). Unique per execution of the routine. |
recurring_delivery_key | string | Identifier of the routine. Present only in report.recurring_delivery_destination_completed — it is stable across executions and serves to identify which routine the delivery came from. |
description | string | Description registered in the routine. Present only in report.recurring_delivery_destination_completed. |
destination | object | Completed destination. See destination attributes. |
reports | array | Reports of the delivery. See reports attributes. |
destination attributes
| Field | Type | Description |
|---|---|---|
destination_key | string | Identifier of the destination (UUID). It is the key of this notification: a destination_key is notified only once. |
destination_type | string (enum) | sftp or email. |
status | string (enum) | delivered or failed. See the when it is sent table. |
folder_path | string | Destination folder on the SFTP. Present only when destination_type is sftp. |
recipients | array | Recipients of the e-mail. Present only when destination_type is email. |
title | string | Subject of the e-mail. Present only when destination_type is email. |
The files are written to folder_path with exactly the file_name of each report — the full path is {folder_path}/{file_name}.
reports attributes
| Field | Type | Description |
|---|---|---|
report_type | string (enum) | Model of the report, as shown in the "Model" column of the list of available reports. |
file_name | string | Name of the delivered file, already with the fund prefix and the date. |
fund_class_key | string | Fund class of the report. |
reference_date | string | Reference date, in YYYY-MM-DD. It may come null in the reports generated by range (quota_mec, balance_report, accounting_ledger), which are parameterized by start_date and end_date instead of a single date — treat the field as optional and use file_name to identify the file. |
status | string (enum) | generated or failed. |
status of each reportA webhook received does not mean that all the files are in the folder. Reports with status: "failed" appear in the list and have no corresponding file.
A reader that iterates over reports and tries to download everything will fail on the first report with an error. Filter by status == "generated" before assembling the list of files to collect, and treat the presence of failed as an operational alert — not as an absence of delivery.
Authentication and resending
The signature validation, the list of source IPs, the retry policy and the resending are the same as for the other QI CTVM webhooks — see Receiving Webhooks.
Where there is no webhook
Two report deliveries do not emit this notification:
- Assignment reports — the Assignment Collateral and the Assignment Assets Composition are generated at the assignment approval stage, not in the fund's routine. For those two, tracking is done through the assignment batch status webhook and by collecting from the folder.
- On-demand portfolio download — the Download the Portfolio route is synchronous and returns the file in the response itself, in base64. It does not go through a delivery, a destination, nor a webhook.
assignment_documents is precisely the report where an arrival notice would make the most difference, because the download links inside it expire 5 days after generation. Since it does not emit a webhook, the collection guidance remains the one in the Testing the Collateral Capture walkthrough.