Report webhook events

This guide documents the webhook event types available for the reports domain. Webhooks enable you to track report generation and be notified immediately when reports are created, eliminating the need to poll for status updates.

Event types overview

Upvest sends webhook notifications whenever a report is created for an end user or as part of a business process. The REPORT.CREATED event fires immediately when a new report is generated, allowing your application to be notified and retrieve the report.

Reports are generated by Upvest's background processes when triggered by business events — such as when a user places an order, receives a corporate action, or completes a tax collection cycle. Each report type is documented in the End user reports and Regulatory reports guides.

Report event table

Event type	Trigger	Status	Description
REPORT.CREATED	Automatic	Immediate	A new report has been generated and is ready for retrieval. The webhook payload includes the report ID, type, user ID, and related reference information.

Report generation lifecycle

Reports are generated automatically when triggered by specific business events. The following diagram shows the typical report lifecycle:

Order placed / Corporate action / Tax collection event
            ↓
      Report generation
            ↓
      REPORT.CREATED webhook sent
            ↓
      Report ready for retrieval
            ↓
      Download / process report

Your webhook handler is immediately notified when the report is available.

REPORT.CREATED event

The REPORT.CREATED event is sent when Upvest generates a new report for an end user or business process.

Event payload

{
  "id": "8962b496-8d42-4560-bfab-10490dd1a721",
  "created_at": "2021-07-21T14:10:00.00Z",
  "type": "REPORT.CREATED",
  "object": {
    "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
    "created_at": "2020-08-24T14:15:22Z",
    "user_id": "d1a4be99-8bb6-4e78-b897-8168f6823ab5",
    "type": "CORPORATE_ACTION_CASH_TRANSACTION",
    "substituted_report_id": null,
    "data": {
      "account": {
          "id": "a9a4ad54-6dd1-419a-a98d-ab48f9f23bc8"
      },
      "references": [
        {
          "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
          "type": "CORPORATE_ACTION_TRANSACTION_ID"
        }
      ]
    }
  },
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Field descriptions

Field	Type	Description
`id`	string (UUID).	Unique identifier for this webhook event.
`created_at`	string (ISO 8601 timestamp).	When the webhook event was created (UTC).
`type`	string	Event type: always `REPORT.CREATED`.
`object.id`	string (UUID).	Report ID — use this to retrieve the report via `GET /reports/{report_id}`.
`object.created_at`	string (ISO 8601 timestamp).	When the report was generated (UTC).
`object.user_id`	string (UUID).	The end user for whom the report was created.
`object.type`	string	Report type (e.g., `BUY_ORDER`, `ANNUAL_TAX_STATEMENT`, `CORPORATE_ACTION_CASH_TRANSACTION`) — see User report types for complete list.
`object.substituted_report_id`	string (UUID) or null.	If this report replaces a previous report, this field contains the ID of the replaced report; otherwise `null`.
`object.data.account.id`	string (UUID).	Account ID associated with the report (when applicable).
`object.data.references`	array	Array of references linking the report to related business objects (e.g., corporate actions, transactions).
`webhook_id`	string (UUID).	Unique identifier for this webhook subscription — used for debugging.

Recommended workflow

Follow these steps to implement report generation tracking via webhooks:

Set up webhook handler
Create an HTTP endpoint to listen for incoming webhooks. Endpoint must validate webhook signatures and respond with HTTP 200 within 30 seconds.
For more information, refer to Implementing webhooks
Subscribe to REPORT.CREATED events
Call POST /webhooks with event_type: "REPORT.CREATED" to subscribe.
For more information, refer to Webhook subscription
Handle REPORT.CREATED webhook
When your handler receives the webhook event, extract the object.id (report ID). Store the report ID in your application state, linked to the user.
Retrieve report on demand
When the end user requests the report, call GET /reports/{report_id} with the appropriate Accept header:
- Accept: application/pdf for PDF format
- Accept: application/json for JSON format (ex-ante reports only)
  For more information, refer to Retrieve report
Optional: Filter by report type
In your webhook handler, check object.type to filter reports by type if needed (e.g., only process tax-related reports). See User report types for the complete list.