Webhook de Entrega

Visão Geral

Sempre que uma entrega de relatórios é concluída, a QI CTVM pode notificar a sua aplicação por webhook. A notificação diz qual entrega terminou, para qual destino, e quais arquivos ela levou — com o status de cada relatório. É o sinal para você disparar a coleta no SFTP em vez de varrer a pasta em intervalos fixos.

O webhook é opcional e configurado por rotina de entrega. Sem configuração, nenhuma notificação é enviada.

Como habilitar

Informe ao time de integração a URL que vai receber as notificações. Devolvemos uma Signature Key para você validar a assinatura, e vinculamos a configuração à rotina de entrega do fundo. A habilitação é por rotina — um fundo com duas rotinas configura as duas.

Quando é enviado

Uma notificação por destino concluído, no momento em que aquele destino termina de ser processado.

Um destino só é processado depois que todos os relatórios da entrega chegam a um estado final — generated ou failed. Só então os arquivos são transferidos e a notificação sai. Ou seja: quando o webhook chega, a pasta já tem os arquivos.

Situação	Status do destino	Webhook
Todos os relatórios gerados	delivered	enviado
Parte dos relatórios falhou	delivered	enviado — os que falharam aparecem em reports, mas não têm arquivo na pasta
Todos os relatórios falharam	failed	enviado — nenhum arquivo é transferido

É um webhook por destino, não por arquivo

Uma rotina que entrega oito relatórios em uma pasta SFTP gera uma notificação, com oito entradas em reports. Não há uma notificação por arquivo.

Se a mesma entrega tem dois destinos — por exemplo uma pasta SFTP e um e-mail — são duas notificações, uma por destino, e as duas trazem a mesma lista de reports.

Cada destino é notificado uma única vez

A notificação de um destino é registrada quando é enviada e não se repete. Um reprocessamento do envio não gera notificação nova. Para reenviar uma notificação já emitida, veja Recebimento de Webhooks.

Tipos de webhook

webhook_type	Quando
report.recurring_delivery_destination_completed	Entrega originada de uma rotina — o caso da entrega diária de relatórios do fundo.
report.delivery_destination_completed	Entrega avulsa, criada fora da rotina.

A diferença de payload está em data: o tipo de rotina acrescenta recurring_delivery_key e description.

Estrutura do webhook

Webhook Body — rotina, destino SFTP

{
    "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"
            }
        ]
    }
}

Atributos de data

Campo	Tipo	Descrição
solicitation_time	string	Data e hora em que a entrega foi solicitada, em ISO 8601 (UTC).
delivery_key	string	Identificador da entrega (UUID). Único por execução da rotina.
recurring_delivery_key	string	Identificador da rotina. Presente apenas em report.recurring_delivery_destination_completed — é estável entre execuções e serve para identificar de qual rotina veio a entrega.
description	string	Descrição cadastrada na rotina. Presente apenas em report.recurring_delivery_destination_completed.
destination	object	Destino concluído. Veja Atributos de destination.
reports	array	Relatórios da entrega. Veja Atributos de reports.

Atributos de destination

Campo	Tipo	Descrição
destination_key	string	Identificador do destino (UUID). É a chave desta notificação: um destination_key é notificado uma única vez.
destination_type	string (enum)	sftp ou email.
status	string (enum)	delivered ou failed. Veja a tabela de quando é enviado.
folder_path	string	Pasta de destino no SFTP. Presente apenas quando destination_type é sftp.
recipients	array	Destinatários do e-mail. Presente apenas quando destination_type é email.
title	string	Assunto do e-mail. Presente apenas quando destination_type é email.

Os arquivos são gravados em folder_path com exatamente o file_name de cada relatório — o caminho completo é {folder_path}/{file_name}.

Atributos de reports

Campo	Tipo	Descrição
report_type	string (enum)	Modelo do relatório, conforme a coluna "Modelo" da lista de relatórios disponíveis.
file_name	string	Nome do arquivo entregue, já com o prefixo do fundo e a data.
fund_class_key	string	Classe de fundo do relatório.
reference_date	string	Data de referência, em AAAA-MM-DD. Pode vir nulo nos relatórios gerados por intervalo (quota_mec, balance_report, accounting_ledger), que são parametrizados por start_date e end_date em vez de uma data única — trate o campo como opcional e use file_name para identificar o arquivo.
status	string (enum)	generated ou failed.

Confira o status de cada relatório

Um webhook recebido não significa que todos os arquivos estão na pasta. Relatórios com status: "failed" aparecem na lista e não têm arquivo correspondente.

Um leitor que itere reports e tente baixar tudo vai falhar no primeiro relatório com erro. Filtre por status == "generated" antes de montar a lista de arquivos a coletar, e trate a presença de failed como alerta operacional — não como ausência de entrega.

Autenticação e reenvio

A validação da assinatura, a lista de IPs de origem, a política de tentativas e o reenvio são iguais aos dos demais webhooks da QI CTVM — veja Recebimento de Webhooks.

Onde não há webhook

Duas entregas de relatório não emitem esta notificação:

• Relatórios de cessão — o Lastros da Cessão e a Composição de Ativos da Cessão são gerados na etapa de aprovação da cessão, e não na rotina do fundo. Para esses dois, o acompanhamento é pelo webhook de status do lote de cessão e pela coleta na pasta.
• Download sob demanda da carteira — a rota de Baixar a Carteira é síncrona e devolve o arquivo na própria resposta, em base64. Não passa por entrega, destino, nem webhook.

Atenção ao lastro da cessão

O assignment_documents é justamente o relatório em que o aviso de chegada faria mais diferença, porque os links de download dentro dele expiram em 5 dias contados da geração. Como ele não emite webhook, a orientação de coleta continua sendo a do roteiro de Testando a Captura de Lastro.