> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Downloadable reports

> Request large data reports asynchronously and receive webhook notifications when files are ready to download.

Downloadable reports enable you to request data reports and have Tesouro notify you via a webhook when the files are ready to download.

## Key Benefits

**Accommodates Large Reports:** Downloadable reports are well-suited for handling large reports containing millions of records, which could otherwise lead to extended download times or potential timeouts in a traditional synchronous request-response model.

**Enhanced efficiency:** By decoupling report generation from the initial request, reports allow for efficient resource utilization and improved user experience, as users are not blocked while reports are being processed.

This is the flow to request a report:

## Workflow

1. Report request:
   * The system user initiates a report request by calling the corresponding mutation.
   * The request should include the filters including date range and any other optional filter.
   * Tesouro sends a response that includes a `requestId` that will be used later to request the completed report status.
2. Asynchronous processing:
   * Tesouro acknowledges the request and begins report generation in the background.
3. Webhook notification:
   * Upon completion, Tesouro sends a notification to your designated webhook, containing a link to retrieve the generated report file, including the created and expiration timestamps.
4. Report download:
   * Follow the provided link to download the completed report.

<Info>
  When the report expires, the file is deleted and no longer available for download. You can request
  a new report to be generated.
</Info>

## Setup

Complete these steps before requesting any downloadable reports, as Tesouro encrypts them for security.

* Generate a PGP key pair. Choose the following algorithm and key size:
  * Algorithm: RSA
  * Key Size: 4096 bits
* Securely store the private key and employ it for decrypting files received from Tesouro, as well as for verifying the signature
  of webhook requests.
* Coordinate to securely send the public key to Tesouro. Tesouro will use the public key to encrypt the report file and sign
  the message sent to the webhook endpoint.

<Info>
  Please note that you would need to regenerate a new key pair before the current key pair expires
  to ensure that the communication between Tesouro's servers and yours are always secure.
</Info>

## Webhook Configuration

Contact Tesouro to configure your webhook. You need to implement a webhook with the following specification:

* Implement a webhook endpoint that only accepts POST requests over HTTPS.

Here is the JSON body format:

| Field name            | Type     | Description                                                                             |
| --------------------- | -------- | --------------------------------------------------------------------------------------- |
| `requestId`           | uuid     | The Id first generated by Tesouro when the request for the report was submitted         |
| `deliveryId`          | uuid     | The Id of this attempt to call the webhook endpoint                                     |
| `presenterId`         | uuid     | The presenterId that initiated the request                                              |
| `fileUrl`             | STRING   | The URL to the downloadable file                                                        |
| `createDateTimeUtc`   | dateTime | The time that the report was created                                                    |
| `expireDateTimeUtc`   | dateTime | The time that the report will expire                                                    |
| `deliveryDateTimeUtc` | dateTime | The time that the webhook is called                                                     |
| `numberOfAttempts`    | int      | Number of times Tesouro attempted to call the webhook, in case Tesouro received failure |

Be sure to return response code `200` to confirm delivery and ensure webhook is not re-sent.

```http title="Webhook request" lines theme={null}
POST /webhook HTTP/2
Host: example.com
Content-Type: application/json

{
  "requestId": "03635182-bdb5-41cc-8bda-1fbbaf444476",
  "deliveryId": "960918fc-4885-4288-adfe-64417c27ed63",
  "presenterId": "1b6592dc-0398-452a-a468-d02bd8707b73",
  "fileUrl": "http://download.tesouro.com/report1.gpg",
  "createDateTimeUtc": "2023-12-21T23:06:18",
  "expireDateTimeUtc": "2023-12-24T23:06:18",
  "deliveryDateTimeUtc": "2023-12-21T23:07:18",
  "numberOfAttempts": 1
}
```

```http title="Webhook response" lines theme={null}
HTTP/2 200
```