Skip to main content
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.
When the report expires, the file is deleted and no longer available for download. You can request a new report to be generated.

​
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.
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.

​
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 nameTypeDescription
requestIduuidThe Id first generated by Tesouro when the request for the report was submitted
deliveryIduuidThe Id of this attempt to call the webhook endpoint
presenterIduuidThe presenterId that initiated the request
fileUrlSTRINGThe URL to the downloadable file
createDateTimeUtcdateTimeThe time that the report was created
expireDateTimeUtcdateTimeThe time that the report will expire
deliveryDateTimeUtcdateTimeThe time that the webhook is called
numberOfAttemptsintNumber 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.
Webhook request
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
}
Webhook response
HTTP/2 200