> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Event Types
> Every event type you can subscribe to, the payload each one carries, and the API endpoint its entries match.
This is the complete catalog of event types. Each entry names the payload shape it carries and the API endpoint its entries match, so you can reuse parsers you have already written.
For how delivery, retries, and signature verification work, see the [Webhooks reference](/webhooks).
## Envelope
Every delivery is a `POST` of the same JSON envelope. Only `data.object` varies by event type.
| Field | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------------ |
| `id` | string (UUID) | The event id. Use this for idempotency / deduplication. |
| `type` | string | The event type, e.g. `earnings.created`. |
| `api_version` | string | The API version pinned on your destination (date-stamped). |
| `livemode` | boolean | `false` for test events fired from the dashboard, `true` for production. |
| `created` | integer | Unix timestamp (seconds) of when we recorded the event. |
| `data.object` | object | The resource payload. Shape depends on `type`. |
## Payload shapes
Three shapes cover every event type that carries a dataset array, and each catalog entry below names which one it uses. `filing_items.metadata.created` is the exception: it carries filing metadata rather than data, and its shape is documented with the event itself.
### Filing-level
Used by the four statement events, the three segment events, and the two insider events. A header identifying the filing, plus an array named after the event's dataset.
| Field | Type | Description |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `ticker` | string | Ticker of the company that filed. |
| `accession_number` | string | The SEC's unique id for this filing. |
| `filing_date` | string (date) \| null | Date the filing was filed with the SEC. |
| `form_type` | string | The form as filed, so amendments keep their suffix: `10-K`, `10-Q`, `20-F`, `6-K`, `4`, `3`, or an amendment such as `10-Q/A`. |
| *dataset key* | array | The dataset's entries for this filing. The key matches the event type: an `income_statements.created` event carries `income_statements`. |
Each array entry is identical to a single entry from the corresponding API response.
**Header vs. entry `form_type`.** Statement entries carry their own `form_type` recording which form that row came from. It matches the header for the filing's reported period, and is `null` on `ttm` entries, because a trailing twelve month window can span multiple filings. Read the header when you want the filing; read the entry when you want that row's provenance. Segment entries carry no `form_type`, `filing_date`, or `filing_datetime`.
### Release-level
Used by the three earnings intelligence events. Keyed to an earnings release rather than a filing period.
| Field | Type | Description |
| ------------------ | --------------------- | ----------------------------------------------------------------------- |
| `ticker` | string | Ticker of the company that reported. |
| `accession_number` | string | The SEC's unique id for the earnings release filing. |
| `sector` | string | The sector whose KPI definitions we applied. |
| `report_period` | string (date) \| null | The fiscal period the release covers. |
| *dataset key* | array | The dataset's entries for this release. The key matches the event type. |
### Earnings
Used only by `earnings.created`. The `data.object` is a single entry from the [`GET /earnings/`](/api/earnings) response, with no wrapper array.
## Event types
Listed alphabetically.
### `balance_sheets.created`
Fires when a filing's balance sheets are extracted, within minutes of a 10-K, 10-Q, 20-F, or 6-K being processed.
Shape: [filing-level](#filing-level), carrying `balance_sheets`. Entries match [`GET /financials/balance-sheets`](/api/financials/balance-sheets).
### `balance_sheet_segments.created`
Fires when a filing reports balance sheet segment breakdowns. Balance sheet segments are rarer than income statement segments, so expect this event for fewer filings.
Shape: [filing-level](#filing-level), carrying `balance_sheet_segments`. Entries match [`GET /financials/balance-sheets/segments`](/api/financials/balance-sheet-segments).
### `cash_flow_statements.created`
Fires when a filing's cash flow statements are extracted, within minutes of a 10-K, 10-Q, 20-F, or 6-K being processed.
Shape: [filing-level](#filing-level), carrying `cash_flow_statements`. Entries match [`GET /financials/cash-flow-statements`](/api/financials/cash-flow-statements).
### `cash_flow_statement_segments.created`
Fires when a filing reports cash flow statement segment breakdowns. Like balance sheet segments, these are reported by fewer filings.
Shape: [filing-level](#filing-level), carrying `cash_flow_statement_segments`. Entries match [`GET /financials/cash-flow-statements/segments`](/api/financials/cash-flow-statement-segments).
### `earnings.created`
Fires when we parse a new earnings release (8-K) or quarterly/annual report, within minutes of the filing hitting EDGAR.
Shape: [earnings](#earnings). The `data.object` is a single [`GET /earnings/`](/api/earnings) entry, so any parser written against the Earnings API works unchanged.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"id": "04b97437-62cd-4ccb-b7eb-54765dbaa72d",
"type": "earnings.created",
"api_version": "2026-05-20",
"livemode": true,
"created": 1779309269,
"data": {
"object": {
"ticker": "NDSN",
"report_period": "2026-04-30",
"fiscal_period": "2026-Q2",
"currency": "USD",
"source_type": "8-K",
"filing_date": "2026-05-20",
"filing_datetime": "2026-05-20T16:33:44-04:00",
"filing_url": "https://www.sec.gov/Archives/edgar/data/72331/000007233126000022/0000072331-26-000022-index.htm",
"accession_number": "0000072331-26-000022",
"quarterly": {
"revenue": 740847000,
"net_income": 117316000,
"earnings_per_share": 2.10,
"...": "see Earnings API reference"
}
}
}
}
```
**A single quarter can fire more than one `earnings.created` event.** The 8-K earnings release fires first, then the 10-Q (or 10-K for the fiscal-year quarter) follows 30 to 45 days later with the full GAAP-audited numbers. Both carry the same `(ticker, report_period)` but different `accession_number`s and different `source_type`s. See [Handling multiple earnings events](#handling-multiple-earnings-events) below.
### `filing_items.metadata.created`
Fires when a filing's items become available, which is the moment [`GET /filings/items`](/api/filings/items) can serve them quickly. Covers 10-K, 10-Q, and 8-K filings and their amendments (`10-K/A`, `10-Q/A`, `8-K/A`), one event per filing.
**This event carries metadata, not filing text.** Filing text runs to megabytes, which would blow the 10 second delivery deadline, so the payload gives you the filing header, the items it contains, and a `url` to fetch the text from. Treat it as a notification to go pull, not as the data itself.
| Field | Type | Description |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `ticker` | string | Ticker of the company that filed. |
| `cik` | string | The company's 10-digit zero-padded SEC CIK. |
| `accession_number` | string | The SEC's unique id for this filing. |
| `filing_type` | string | The form as filed, so amendments keep their suffix: `10-K`, `10-Q`, `8-K`, `10-K/A`, `10-Q/A`, or `8-K/A`. |
| `filing_date` | string (date) \| null | Date the filing was filed with the SEC. |
| `available_items` | array of string | The items this filing actually contains, in the exact form the `item` query parameter accepts. |
| `url` | string | Ready-to-call `GET /filings/items` URL for the full payload. |
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"id": "b3f1c2d4-5e6a-47b8-9c0d-1e2f3a4b5c6d",
"type": "filing_items.metadata.created",
"api_version": "2026-05-20",
"livemode": true,
"created": 1783291200,
"data": {
"object": {
"ticker": "AAPL",
"cik": "0000320193",
"accession_number": "0000320193-26-000002",
"filing_type": "8-K",
"filing_date": "2026-02-19",
"available_items": ["Item-2.02", "Item-9.01"],
"url": "https://api.financialdatasets.ai/filings/items/?ticker=AAPL&filing_type=8-K&accession_number=0000320193-26-000002"
}
}
}
```
**Using `available_items`.** The values are exactly what the `item` query parameter accepts, so you can filter before spending a call. Append `&item=` to the `url` to fetch a single section:
```
https://api.financialdatasets.ai/filings/items/?ticker=AAPL&filing_type=8-K&accession_number=0000320193-26-000002&item=Item-2.02
```
Item naming follows the filing family: 10-K items look like `Item-1A`, 10-Q items are part-qualified as `Part-1,Item-2`, and 8-K items carry their decimal number as `Item-2.02`. A filing contains any subset, so check `available_items` rather than assuming a given item is present. This makes the event a cheap filter: an agent that only cares about earnings releases can watch for `Item-2.02` and ignore every other 8-K without fetching anything.
Fetching the `url` is a normal billed API call, and it hits a warm cache. See [`GET /filings/items`](/api/filings/items) for the response schema and the full list of item names.
### `financial_metrics.created`
Fires when a filing's financial metrics (valuation, margins, ratios, growth) are computed.
Shape: [filing-level](#filing-level), carrying `financial_metrics`. Entries match [`GET /financial-metrics`](/api/financial-metrics/historical).
### `forward_guidance.created`
Fires when an earnings release contains forward guidance, minutes after `earnings.created` once we finish analyzing the release.
Shape: [release-level](#release-level), carrying `forward_guidance`. Entries match [`GET /kpi/guidance`](/api/kpi/guidance).
### `income_statements.created`
Fires when a filing's income statements are extracted, within minutes of a 10-K, 10-Q, 20-F, or 6-K being processed.
Shape: [filing-level](#filing-level), carrying `income_statements`. Entries match [`GET /financials/income-statements`](/api/financials/income-statements).
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"id": "1d2f5a80-93c4-4e0f-8a1c-6b7d2e9f4a31",
"type": "income_statements.created",
"api_version": "2026-05-20",
"livemode": true,
"created": 1783208305,
"data": {
"object": {
"ticker": "TXN",
"accession_number": "0000097476-26-000060",
"filing_date": "2026-04-23",
"form_type": "10-Q",
"income_statements": [
{
"ticker": "TXN",
"report_period": "2026-03-31",
"fiscal_period": "2026-Q1",
"period": "quarterly",
"currency": "USD",
"revenue": 4742000000.0,
"net_income": 1364000000.0,
"...": "see the Income Statements API reference"
}
]
}
}
}
```
A filing usually produces one entry per array. When we can also compute a trailing-twelve-months view from it, a second entry with `"period": "ttm"` appears alongside the quarterly or annual one. Entries are ordered by period type, so on annual filings the `ttm` entry comes first.
### `income_statement_segments.created`
Fires when a filing reports income statement segment breakdowns. This is the most common of the three segment events.
Shape: [filing-level](#filing-level), carrying `income_statement_segments`. Entries match [`GET /financials/income-statements/segments`](/api/financials/income-statement-segments).
### `insider_ownership.created`
Fires when an insider reports positions they hold rather than trades: SEC Form 3 initial ownership statements, Form 5 filings that include holdings, and their amendments (`3/A`, `5/A`). One event per filing, delivered once daily in the early morning UTC covering the previous day's filings.
Shape: [filing-level](#filing-level), carrying `insider_ownership`. Entries match [`GET /insider-ownership`](/api/insider-ownership).
A single Form 5 that reports both transactions and holdings fires **both** events: one `insider_trades.created` and one `insider_ownership.created`, sharing the same `accession_number`.
Each entry describes one held position:
| Field | Type | Description |
| ------------------------------ | -------------- | -------------------------------------------------------------------------------------- |
| `ticker` | string | Ticker of the issuer whose securities are held. |
| `issuer` | string | Issuer company name. |
| `name` | string | The insider's name. |
| `title` | string \| null | The insider's role at the issuer. |
| `is_board_director` | boolean | Whether the insider sits on the board. |
| `is_officer` | boolean | Whether the insider is an officer of the issuer. |
| `is_ten_percent_owner` | boolean | Whether the insider owns 10%+ of the issuer. |
| `form_type` | string | `3`, `3/A`, `5`, or `5/A`. |
| `filing_date` | string (date) | Date the form was filed with the SEC. |
| `as_of_date` | string (date) | Date the position is stated as of. |
| `accession_number` | string | The SEC accession number of the filing. |
| `holding_type` | string | `common` or `derivative`. Derivative-only fields below are `null` on `common` entries. |
| `security_title` | string | Title of the held security. |
| `shares_owned` | number | Shares (or units) beneficially owned. |
| `direct_or_indirect` | string | `D` (held directly) or `I` (held indirectly). |
| `nature_of_ownership` | string \| null | For indirect holdings, the ownership vehicle (e.g. a trust or LLC). |
| `conversion_or_exercise_price` | number \| null | Derivative only: conversion or exercise price. |
| `exercise_date` | string \| null | Derivative only: date first exercisable. |
| `expiration_date` | string \| null | Derivative only: expiration date. |
| `underlying_security_title` | string \| null | Derivative only: title of the underlying security. |
| `underlying_security_shares` | number \| null | Derivative only: number of underlying shares. |
### `insider_trades.created`
Fires when a company insider reports buying or selling stock: SEC Form 4, Form 5 annual statements that include transactions, and their amendments (`4/A`, `5/A`). One event per filing, delivered once daily in the early morning UTC covering the previous day's filings.
Shape: [filing-level](#filing-level), carrying `insider_trades`, with one entry per reported transaction in filing order. Entries match [`GET /insider-trades`](/api/insider-trades).
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"id": "8f3c0a51-2f6e-4d1b-9a77-c9d4e2b81f02",
"type": "insider_trades.created",
"api_version": "2026-05-20",
"livemode": true,
"created": 1783148405,
"data": {
"object": {
"ticker": "NVDA",
"accession_number": "0001045810-26-000214",
"filing_date": "2026-07-06",
"form_type": "4",
"insider_trades": [
{
"ticker": "NVDA",
"issuer": "NVIDIA Corp",
"name": "JENSEN HUANG",
"title": "CEO",
"is_board_director": true,
"filing_date": "2026-07-06",
"report_period": "2026-07-02",
"transaction_date": "2026-07-02",
"transaction_code": "S",
"transaction_type": "Open market sale",
"transaction_shares": 75000.0,
"transaction_price_per_share": 157.32,
"transaction_value": 11799000.0,
"shares_owned_before_transaction": 75600000.0,
"shares_owned_after_transaction": 75525000.0,
"security_title": "Common Stock"
}
]
}
}
}
```
**Amendments.** An amendment (`4/A`, `5/A`) is its own filing with its own `accession_number`, so it fires its own event containing the complete, amended set of transactions. Treat its contents as replacing what the original filing reported.
### `non_gaap_metrics.created`
Fires when an earnings release contains non-GAAP metrics, minutes after `earnings.created`.
Shape: [release-level](#release-level), carrying `non_gaap_metrics`. Entries match [`GET /kpi/non-gaap`](/api/kpi/non-gaap).
### `operating_kpis.created`
Fires when operating KPIs are extracted from a new earnings release, minutes after `earnings.created`.
Shape: [release-level](#release-level), carrying `operating_kpis`. Entries match [`GET /kpi/metrics`](/api/kpi/metrics).
## Handling multiple earnings events
A single quarter of earnings can produce more than one `earnings.created` event as the SEC filing chain progresses:
1. The **8-K** earnings release fires first, typically hours after announcement.
2. The **10-Q** (or **10-K** for the fiscal-year quarter) follows 30 to 45 days later with the full GAAP-audited numbers, segments, and footnotes-derived metrics.
Both events have the same `(ticker, report_period)` but different `accession_number`s and different `data.object.source_type` values (`"8-K"` vs `"10-Q"` vs `"10-K"`).
Three reasonable ways to handle this:
* **Dedupe by `(ticker, report_period)`** — process the first event you see, ignore the later one. Use when latency matters more than completeness.
* **Always process the most recent `source_type`** — keep the 10-Q's richer data, discard the earlier 8-K once it arrives. Use when you need the full GAAP record.
* **Process both** — emit your downstream signal twice. Use when you have separate "first signal" and "final record" consumers, such as real-time alerting plus an analytics warehouse.
The dedup key on our side is `event.id`, the same one we use for retry idempotency. The dedup key on **your** side is `(ticker, report_period)` if you want once-per-quarter semantics. Foreign issuers and microcaps that don't file 8-Ks fire only one event per period (the 10-Q, 10-K, or 20-F).
## Timing summary
| Family | When it arrives |
| ------------------------------ | ------------------------------------------------------------------- |
| Earnings | Within minutes of the filing hitting EDGAR. |
| Financial statements, segments | Within minutes of a 10-K, 10-Q, 20-F, or 6-K being processed. |
| Earnings intelligence | Minutes after `earnings.created`, once analysis completes. |
| Insider activity | Once daily, early morning UTC, covering the previous day's filings. |
| Filings | Within minutes of a 10-K, 10-Q, or 8-K being processed. |
## See also
* [Webhooks reference](/webhooks) — delivery, retries, signature verification, debugging.
* [How to set up webhooks](/guides/setup-webhooks) — step-by-step with a working Python receiver.