Webhook Event Types

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.

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/ 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, carrying balance_sheets. Entries match GET /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, carrying balance_sheet_segments. Entries match GET /financials/balance-sheets/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, carrying cash_flow_statements. Entries match GET /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, carrying cash_flow_statement_segments. Entries match GET /financials/cash-flow-statements/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. The data.object is a single GET /earnings/ entry, so any parser written against the Earnings API works unchanged.

{
  "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_numbers and different source_types. See Handling multiple earnings events below.

`filing_items.metadata.created`

Fires when a filing’s items become available, which is the moment GET /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.

{
  "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=<name> 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 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, carrying financial_metrics. Entries match GET /financial-metrics.

`forward_guidance.created`

Fires when an earnings release contains forward guidance, minutes after earnings.created once we finish analyzing the release. Shape: release-level, carrying forward_guidance. Entries match GET /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, carrying income_statements. Entries match GET /financials/income-statements.

{
  "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, carrying income_statement_segments. Entries match GET /financials/income-statements/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, carrying insider_ownership. Entries match GET /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, carrying insider_trades, with one entry per reported transaction in filing order. Entries match GET /insider-trades.

{
  "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, carrying non_gaap_metrics. Entries match GET /kpi/non-gaap.

`operating_kpis.created`

Fires when operating KPIs are extracted from a new earnings release, minutes after earnings.created. Shape: release-level, carrying operating_kpis. Entries match GET /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:

The 8-K earnings release fires first, typically hours after announcement.
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_numbers 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.

Overview

Integrations

Datasets

Guides

Envelope

Payload shapes

Filing-level

Release-level

Earnings

Event types

`balance_sheets.created`

`balance_sheet_segments.created`

`cash_flow_statements.created`

`cash_flow_statement_segments.created`

`earnings.created`

`filing_items.metadata.created`

`financial_metrics.created`

`forward_guidance.created`

`income_statements.created`

`income_statement_segments.created`

`insider_ownership.created`

`insider_trades.created`

`non_gaap_metrics.created`

`operating_kpis.created`

Handling multiple earnings events

Timing summary

See also

​Envelope

​Payload shapes

​Filing-level

​Release-level

​Earnings

​Event types

​balance_sheets.created

​balance_sheet_segments.created

​cash_flow_statements.created

​cash_flow_statement_segments.created

​earnings.created

​filing_items.metadata.created

​financial_metrics.created

​forward_guidance.created

​income_statements.created

​income_statement_segments.created

​insider_ownership.created

​insider_trades.created

​non_gaap_metrics.created

​operating_kpis.created

​Handling multiple earnings events

​Timing summary

​See also

Envelope

Payload shapes

Filing-level

Release-level

Earnings

Event types

`balance_sheets.created`

`balance_sheet_segments.created`

`cash_flow_statements.created`

`cash_flow_statement_segments.created`

`earnings.created`

`filing_items.metadata.created`

`financial_metrics.created`

`forward_guidance.created`

`income_statements.created`

`income_statement_segments.created`

`insider_ownership.created`

`insider_trades.created`

`non_gaap_metrics.created`

`operating_kpis.created`

Handling multiple earnings events

Timing summary

See also