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

Four shapes cover every event type that carries data, 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.

Print-level

Used by the four macro events. A date header naming the print, plus the same body the dataset’s snapshot endpoint returns, under the same key.

Field	Type	Description
`date`	string (date)	The print’s date: the business day for the yield curve, the first day of the reference month for inflation, the newest reference period of the release for the labor market, the first day a new policy rate is in effect for interest rates.
`release`	string	Labor market only: `jobs_report`, `job_openings`, or `jobless_claims`.
`bank`	string	Interest rates only: the central bank code, e.g. `FED`.
dataset key	object \| array	Identical to the body of the corresponding snapshot response: `yield_curve` is one object, `inflation`, `labor`, and `interest_rates` are arrays with one entry per series (one entry, the bank’s row, for interest rates).

One event per dataset per new date (per release for the labor market, per bank per rate change for interest rates). A later revision of an already published date does not fire a new event; the snapshot and history endpoints serve the revised values.

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.

`inflation.created`

Fires when a new month of consumer price index data is published, within hours of the monthly release. One event per reference month, carrying every series we track. Shape: print-level, carrying inflation. The array is identical to the body of GET /macro/inflation/snapshot: one entry per series, each with the index level and the month-over-month and year-over-year percent changes.

{
  "id": "c7e2a9f4-1b3d-4e5f-8a6b-9c0d1e2f3a4b",
  "type": "inflation.created",
  "api_version": "2026-05-20",
  "livemode": true,
  "created": 1789560000,
  "data": {
    "object": {
      "date": "2026-08-01",
      "inflation": [
        {
          "series": "cpi_all_sa",
          "date": "2026-08-01",
          "value": 334.131,
          "change_1m_pct": 0.4,
          "change_12m_pct": 3.4
        },
        {
          "series": "cpi_all_nsa",
          "date": "2026-08-01",
          "value": 334.98,
          "change_1m_pct": 0.3,
          "change_12m_pct": 3.4
        }
      ]
    }
  }
}

The live event carries one entry per series, twelve in total. date is the reference month as its first day, not the release date, the same convention the Inflation API uses.

`labor.created`

Fires when a new labor market release is published, within hours of the release. One event per release: the monthly jobs report (jobs_report: payrolls, the unemployment rates, participation, hourly earnings), the monthly job openings report (job_openings: job openings, hires, quits), and the weekly jobless claims release (jobless_claims: initial and continued claims, their 4-week averages, the insured unemployment rates). The release field names which one. Shape: print-level, carrying labor plus release. The array is the matching slice of GET /macro/labor/snapshot: one entry per series in the release, each with the value, the change from the prior period, the change from a year earlier, and that change as a percent.

{
  "id": "d8f3b0a5-2c4e-4f60-9b7c-0d1e2f3a4b5c",
  "type": "labor.created",
  "api_version": "2026-05-20",
  "livemode": true,
  "created": 1788600000,
  "data": {
    "object": {
      "date": "2026-08-01",
      "release": "jobs_report",
      "labor": [
        {
          "series": "payrolls_sa",
          "date": "2026-08-01",
          "value": 159075,
          "change_prior": 162,
          "change_year": 603,
          "change_year_pct": 0.4
        },
        {
          "series": "unemployment_rate_sa",
          "date": "2026-08-01",
          "value": 4.1,
          "change_prior": 0.0,
          "change_year": -0.2,
          "change_year_pct": null
        }
      ]
    }
  }
}

The live event carries every series in the release: ten for the jobs report, six for job openings, eight for jobless claims. date is the reference period, not the release date, the same convention the Labor Market API uses. For jobless_claims the header date is the week the initial claims cover; the continued claims and insured unemployment rate entries are dated one week earlier, as the release states them. Weekly values carried by the event are the advance figures; the snapshot and history endpoints serve the final figures once published.

`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.

`interest_rates.created`

Fires when a central bank changes its policy rate. One event per bank per change, dated the first day the new rate is in effect. The source publishes the daily series once a week, so the event arrives up to nine days after the decision. Shape: print-level, carrying interest_rates plus bank. The array holds one entry, the bank’s row for that day, identical to that bank’s entry in GET /macro/interest-rates/snapshot. For the Federal Reserve the rate is the midpoint of the target range.

{
  "id": "f2a6c1d4-8b3e-4c7f-a9d0-5e6f7a8b9c0d",
  "type": "interest_rates.created",
  "api_version": "2026-05-20",
  "livemode": true,
  "created": 1790000000,
  "data": {
    "object": {
      "date": "2026-09-17",
      "bank": "FED",
      "interest_rates": [
        {
          "bank": "FED",
          "name": "Federal Reserve",
          "date": "2026-09-17",
          "rate": 3.875
        }
      ]
    }
  }
}

`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.

`yield_curve.created`

Fires when a new business day of the Treasury yield curve is published, the same evening. One event per business day. Shape: print-level, carrying yield_curve. The object is identical to the body of GET /macro/yield-curve/snapshot: the date plus one key per tenor, null where a tenor was not published that day.

{
  "id": "e1f4b7a2-6c8d-4a9e-b0f1-2d3c4b5a6e7f",
  "type": "yield_curve.created",
  "api_version": "2026-05-20",
  "livemode": true,
  "created": 1789431000,
  "data": {
    "object": {
      "date": "2026-09-14",
      "yield_curve": {
        "date": "2026-09-14",
        "1_month": 3.94,
        "1_5_month": 4.0,
        "2_month": 4.06,
        "3_month": 4.11,
        "4_month": 4.18,
        "6_month": 4.18,
        "1_year": 4.37,
        "2_year": 4.65,
        "3_year": 4.73,
        "5_year": 4.8,
        "7_year": 4.88,
        "10_year": 4.97,
        "20_year": 5.37,
        "30_year": 5.34
      }
    }
  }
}

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.
Macroeconomics	The evening a new yield curve day is published; within hours of each monthly consumer price release.

Overview

Integrations

Search

Datasets

Guides

Envelope

Payload shapes

Filing-level

Release-level

Earnings

Print-level

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`

`inflation.created`

`labor.created`

`insider_ownership.created`

`insider_trades.created`

`interest_rates.created`

`non_gaap_metrics.created`

`operating_kpis.created`

`yield_curve.created`

Handling multiple earnings events

Timing summary

See also

​Envelope

​Payload shapes

​Filing-level

​Release-level

​Earnings

​Print-level

​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

​inflation.created

​labor.created

​insider_ownership.created

​insider_trades.created

​interest_rates.created

​non_gaap_metrics.created

​operating_kpis.created

​yield_curve.created

​Handling multiple earnings events

​Timing summary

​See also

Envelope

Payload shapes

Filing-level

Release-level

Earnings

Print-level

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`

`inflation.created`

`labor.created`

`insider_ownership.created`

`insider_trades.created`

`interest_rates.created`

`non_gaap_metrics.created`

`operating_kpis.created`

`yield_curve.created`

Handling multiple earnings events

Timing summary

See also