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

# Events & Payloads

> The events you can subscribe to and the JSON payload StockInsights sends.

## Event envelope

Every webhook request has the same top-level shape. The specifics of the filing
live under `data`.

```json theme={null}
{
  "id": "evt_9f8c1e2a4b6d",
  "type": "filing.created",
  "api_version": "v1",
  "occurred_at": "2026-07-20T09:31:04Z",
  "data": {
    "...": "event-specific, see below"
  }
}
```

<ResponseField name="id" type="string">
  Unique event identifier, prefixed with `evt_`. Use it to de-duplicate:
  the same event can be delivered more than once.
</ResponseField>

<ResponseField name="type" type="string">
  The event type. One of `filing.created` or `filing.enriched`. This is also sent
  in the `X-StockInsights-Event` header.
</ResponseField>

<ResponseField name="api_version" type="string">
  The payload contract version. Currently `v1`. A breaking change to the payload
  shape bumps this value.
</ResponseField>

<ResponseField name="occurred_at" type="string">
  When the event occurred, as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="data" type="object">
  The event-specific body. Its fields depend on `type` — see below.
</ResponseField>

## Event types vs. what you subscribe to

There are two event **types** on the wire — `filing.created` and
`filing.enriched` — but you subscribe at a finer grain. When configuring a
destination you pick from this catalog, and StockInsights only delivers the ones
you select. The **key** is the identifier shown next to each toggle in the
dashboard:

| Key                          | Subscription               | Delivered as      | How to recognize it                        |
| ---------------------------- | -------------------------- | ----------------- | ------------------------------------------ |
| `announcement.created`       | Announcement created       | `filing.created`  | `data.document_type` is `announcement`     |
| `announcement.summary_ready` | Announcement summary ready | `filing.enriched` | `data.enrichment_type` is `summary`        |
| `quarterly-result.created`   | Quarterly result created   | `filing.created`  | `data.document_type` is `quarterly-result` |

<Note>
  Because several subscriptions map onto the same wire `type`, always branch on
  `data.document_type` (and `data.enrichment_type` for enriched events), not on
  `type` alone.
</Note>

## `filing.created`

Sent when a new filing is ingested — for example a new announcement or a newly
published quarterly result.

```json theme={null}
{
  "id": "evt_9f8c1e2a4b6d",
  "type": "filing.created",
  "api_version": "v1",
  "occurred_at": "2026-07-20T09:31:04Z",
  "data": {
    "filing_id": "a1b2c3d4e5f6",
    "country": "IN",
    "document_type": "announcement",
    "company": {
      "id": "RELIANCE",
      "exchange": "NSE"
    },
    "published_date": "2026-07-20T09:30:00Z",
    "source_url": "https://www.bseindia.com/...",
    "url": "https://api.stockinsights.ai/v1/filings/a1b2c3d4e5f6",
    "period": {
      "year": 2026,
      "quarter": "Q1"
    }
  }
}
```

<ResponseField name="data.filing_id" type="string">
  Identifier of the filing. Pass it to the filings API to fetch the full record.
</ResponseField>

<ResponseField name="data.country" type="string">
  Market the filing belongs to. Currently always `IN`.
</ResponseField>

<ResponseField name="data.document_type" type="string">
  The kind of filing, e.g. `announcement` or `quarterly-result`.
</ResponseField>

<ResponseField name="data.company" type="object">
  The company the filing belongs to.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Company identifier (ticker/symbol).
    </ResponseField>

    <ResponseField name="exchange" type="string">
      Exchange the company is listed on, e.g. `NSE` or `BSE`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.published_date" type="string">
  When the filing was published, as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="data.source_url" type="string">
  Link to the filing's original source document on the exchange or company site.
  May be absent when no valid source link is available.
</ResponseField>

<ResponseField name="data.url" type="string">
  Canonical StockInsights API URL for the filing.
</ResponseField>

<ResponseField name="data.period" type="object">
  Reporting period, when applicable (e.g. for quarterly results). Contains `year`
  (integer) and/or `quarter` (string, e.g. `"Q1"`), and is omitted entirely when
  neither applies — as it is for most announcements.
</ResponseField>

## `filing.enriched`

Sent when an AI enrichment for a filing becomes available — for example an
announcement summary. Carries the same fields as `filing.created`, plus the
enrichment itself.

```json theme={null}
{
  "id": "evt_7a2d5b9c1e3f",
  "type": "filing.enriched",
  "api_version": "v1",
  "occurred_at": "2026-07-20T09:33:12Z",
  "data": {
    "filing_id": "a1b2c3d4e5f6",
    "country": "IN",
    "document_type": "announcement",
    "company": {
      "id": "RELIANCE",
      "exchange": "NSE"
    },
    "published_date": "2026-07-20T09:30:00Z",
    "source_url": "https://www.bseindia.com/...",
    "url": "https://api.stockinsights.ai/v1/filings/a1b2c3d4e5f6",
    "enrichment_type": "summary",
    "enrichment": {
      "summary": "The board approved a dividend of ...",
      "category_id": 12,
      "category": "Dividend",
      "sub_category": "Interim dividend",
      "sentiment": "positive",
      "significance": true
    }
  }
}
```

<ResponseField name="data.enrichment_type" type="string">
  The kind of enrichment. Currently always `summary`.
</ResponseField>

<ResponseField name="data.enrichment" type="object">
  The enrichment content. Its shape depends on `enrichment_type`.

  <Expandable title="properties for enrichment_type: summary">
    <ResponseField name="summary" type="string">
      AI-generated summary of the announcement.
    </ResponseField>

    <ResponseField name="category" type="string">
      Announcement category name, e.g. `Dividend`. May be `null`.
    </ResponseField>

    <ResponseField name="category_id" type="integer">
      Numeric id of the category. May be `null`.
    </ResponseField>

    <ResponseField name="sub_category" type="string">
      Finer-grained classification within the category. May be `null`.
    </ResponseField>

    <ResponseField name="sentiment" type="string">
      Sentiment read from the announcement, e.g. `positive`. May be `null`.
    </ResponseField>

    <ResponseField name="significance" type="boolean">
      Whether the announcement is considered materially significant. May be `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

All other `data.*` fields match [`filing.created`](#filing-created).