# 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 account 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.

## 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, 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 account.

### Event payload

```json
{
  "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. |
| `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:

1. **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](/products/omnibus/getting_started/implementing_webhooks)
2. **Subscribe to REPORT.CREATED events**
Call `POST /webhooks` with `event_type: "REPORT.CREATED"` to subscribe.
For more information, refer to [Webhook subscription](/api/webhook-subscriptions/create_webhook)
3. **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.
4. **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](/api/reports/retrieve_report)
5. **Optional: Filter by report type**
In your webhook handler, check `object.type` to filter reports by type if needed.