Webhooks

Overview

Instead of polling our API for new data, you can register an HTTPS endpoint and we’ll POST to it the moment an event fires. Use webhooks to wake up an agent on a fresh earnings release, new financial statements, extracted KPIs and guidance, or insider filings; push records into your warehouse; or trigger downstream automation.

New to webhooks? The setup guide walks you through a working Python receiver end-to-end in under 15 minutes. This page is the reference you’ll come back to once you’re integrated.

How it works

Five steps to get from zero to receiving events:

Create a destination

Set up your endpoint

Stand up an HTTPS handler that can accept JSON POSTs and read the raw request body. See the setup guide for Python + Node examples.

Verify the signature

Confirm each request came from us using the FD-Signature header. See Verifying the signature.

Test with a canned event

Fire a test event from the dashboard’s destination row and confirm your endpoint returns 2xx within 10 seconds.

Go live

Walk through the production checklist before flipping real customer flows onto your handler.

Webhooks are available on Pro and Enterprise plans. Manage your plan from the dashboard.

Production checklist

Before relying on webhooks for production-critical flows, work through each of these:

Use HTTPS, not HTTP. Your endpoint URL must start with https://. We won’t deliver to plain http:// in production. Security →
Confirm each request actually came from us. Use the FD-Signature header to check authenticity. Skip this and anyone could forge events. How to verify →
Reply within 10 seconds. Send back 200 OK quickly, then do the heavy work in the background. Slow replies count as failures and we’ll retry. Retries →
Don’t process the same event twice. We may deliver the same event more than once. Track which event.id values you’ve handled and skip duplicates. Idempotency →
Keep your signing secret safe. Treat it like a password — never commit it to git, store it in a secret manager, and rotate it from the dashboard if it ever leaks. Security →

Event types

Earnings — within minutes of the filing hitting EDGAR:

Event type	Fires when
`earnings.created`	An earnings release (8-K) or quarterly/annual report is processed for a covered company.

Financial statements — within minutes of a 10-K, 10-Q, 20-F, or 6-K being processed:

Event type	Fires when
`income_statements.created`	The filing’s income statements are extracted.
`balance_sheets.created`	The filing’s balance sheets are extracted.
`cash_flow_statements.created`	The filing’s cash flow statements are extracted.
`financial_metrics.created`	The filing’s financial metrics (valuation, margins, ratios, growth) are computed.

Segmented financials — same filings, only when the filing reports segment breakdowns for that statement:

Event type	Fires when
`income_statement_segments.created`	The filing reports income statement segment breakdowns.
`balance_sheet_segments.created`	The filing reports balance sheet segment breakdowns.
`cash_flow_statement_segments.created`	The filing reports cash flow statement segment breakdowns.

Earnings intelligence — minutes after earnings.created, once we finish analyzing the release; each fires only when the release contains that data:

Event type	Fires when
`operating_kpis.created`	Operating KPIs are extracted from the earnings release.
`forward_guidance.created`	The release contains forward guidance.
`non_gaap_metrics.created`	The release contains non-GAAP metrics.

Insider activity — once daily, early morning UTC, covering the previous day’s filings:

Event type	Fires when
`insider_trades.created`	A company insider reports transactions: Form 4, Form 5 filings that include transactions, and their amendments.
`insider_ownership.created`	A company insider reports positions held: Form 3, Form 5 filings that include holdings, and their amendments.

Payload format

Every delivery is a POST of a JSON envelope wrapping a resource. The envelope itself is identical across event types; data.object carries the resource and its shape depends on the event type.

Envelope

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

`earnings.created` resource

The data.object is identical to a single entry from the GET /earnings/ API response. Any parser you’ve written against the Earnings API will work unchanged against the webhook payload. See the Earnings API reference for the full field schema, types, and worked examples — we don’t duplicate it here so the two stay in lockstep. Here’s an example envelope wrapping a single entry:

{
  "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"
      }
    }
  }
}

Multiple events per earnings period

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–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 in your handler:

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 (e.g., real-time alerting + analytics warehouse).

The dedup key on our side is event.id (the envelope UUID) — 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 will fire only one event per period (the 10-Q / 10-K / 20-F).

Financial statement resources

The four statement events (income_statements.created, balance_sheets.created, cash_flow_statements.created, financial_metrics.created) and the three segment events (income_statement_segments.created, balance_sheet_segments.created, cash_flow_statement_segments.created) share one filing-level data.object shape: 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	`10-K`, `10-Q`, `20-F`, or `6-K`.
`income_statements` (etc.)	array	The dataset’s entries for this filing. The key matches the event type: an `income_statements.created` event carries `income_statements`, a `balance_sheet_segments.created` event carries `balance_sheet_segments`, and so on.

Each array entry is identical to a single entry from the corresponding API response, so any parser you’ve written against these endpoints works unchanged here:

income_statements → GET /financials/income-statements
balance_sheets → GET /financials/balance-sheets
cash_flow_statements → GET /financials/cash-flow-statements
financial_metrics → GET /financial-metrics
income_statement_segments → GET /financials/income-statements/segments
balance_sheet_segments → GET /financials/balance-sheets/segments
cash_flow_statement_segments → GET /financials/cash-flow-statements/segments

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. Example envelope for income_statements.created (fields elided; see the API reference for the full schema):

{
  "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"
        }
      ]
    }
  }
}

The segment events fire only when the filing actually reports segment breakdowns for that statement. Income statement segments are the most common; balance sheet and cash flow segment breakdowns are rarer, so expect those two events for fewer filings.

Earnings intelligence resources

operating_kpis.created, forward_guidance.created, and non_gaap_metrics.created fire minutes after earnings.created, once we finish analyzing the release. Each fires only when the release contains that kind of data, and they share a release-level data.object shape:

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.
`operating_kpis` (etc.)	array	The dataset’s entries for this release. The key matches the event type.

Each array entry is identical to a single entry from the corresponding API response:

operating_kpis → GET /kpi/metrics
forward_guidance → GET /kpi/guidance
non_gaap_metrics → GET /kpi/non-gaap

Because earnings.created fires when the release is parsed and these events fire when the analysis completes, expect a gap of a few minutes between them for the same accession_number. Use the accession number to join the two if your pipeline consumes both.

`insider_trades.created` resource

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. The data.object is a filing-level record: a header identifying the filing, plus an insider_trades array with one entry per reported transaction. Each entry is identical to a single entry from the GET /insider-trades API response, so any parser you’ve written against that API works unchanged here. See the API reference for the full field schema.

Field	Type	Description
`ticker`	string	Ticker of the issuer whose securities were traded.
`accession_number`	string	The SEC’s unique id for this filing.
`filing_date`	string (date)	Date the form was filed with the SEC.
`form_type`	string	`4`, `4/A`, `5`, or `5/A`.
`insider_trades`	array	One entry per transaction, in filing order. Same shape as a `GET /insider-trades` entry.

Example envelope:

{
  "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.

`insider_ownership.created` resource

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.

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.

The data.object carries the same filing-level header as insider_trades.created (ticker, accession_number, filing_date, form_type), with an insider_ownership array in place of insider_trades. 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.

Headers

Every request includes:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`FinancialDatasets-Webhook/1.0`
`FD-Signature`	`t=<unix-ts>,v1=<hex-hmac-sha256>`

Verifying the signature

The FD-Signature header lets you confirm the request actually came from us and wasn’t tampered with. The signature is an HMAC-SHA256 of {timestamp}.{raw_body} using your destination’s signing secret.

Always verify against the raw request bytes. If you parse the body to JSON and re-serialize before hashing, the bytes won’t match and verification will fail.

Python
Node

import hmac
import hashlib
import time

SIGNATURE_MAX_SKEW_SECONDS = 300  # 5 minutes

def verify(raw_body: bytes, header_value: str, secret: str) -> bool:
    try:
        parts = dict(piece.split("=", 1) for piece in header_value.split(","))
        ts = int(parts["t"])
        candidate = parts["v1"]
    except (KeyError, ValueError):
        return False

    # Reject anything outside the skew window — defeats replay attacks
    # if your signing secret ever leaks.
    if abs(int(time.time()) - ts) > SIGNATURE_MAX_SKEW_SECONDS:
        return False

    signing_input = f"{ts}.".encode("utf-8") + raw_body
    expected = hmac.new(
        secret.encode("utf-8"), signing_input, hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(candidate, expected)

import crypto from 'node:crypto'

const SIGNATURE_MAX_SKEW_SECONDS = 300 // 5 minutes

export function verify(rawBody, headerValue, secret) {
  let ts, candidate
  try {
    const parts = Object.fromEntries(
      headerValue.split(',').map((p) => p.split('=', 2)),
    )
    ts = parseInt(parts.t, 10)
    candidate = parts.v1
  } catch {
    return false
  }

  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > SIGNATURE_MAX_SKEW_SECONDS) {
    return false
  }

  const signingInput = Buffer.concat([
    Buffer.from(`${ts}.`, 'utf8'),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8'),
  ])
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signingInput)
    .digest('hex')

  // Lengths must match before timingSafeEqual; otherwise it throws.
  const a = Buffer.from(candidate, 'hex')
  const b = Buffer.from(expected, 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Use a constant-time comparison (hmac.compare_digest / crypto.timingSafeEqual) — a normal == is vulnerable to timing attacks.

Retries

A delivery succeeds when your endpoint returns any 2xx response within 10 seconds. Anything else — a 4xx, a 5xx, a connection error, or a timeout — counts as a failure, and we’ll retry on this schedule:

Attempt	When we try it
1	Immediately, as soon as the event fires.
2	About 1 minute after attempt 1 (±10s of jitter).
3	About 10 minutes after attempt 2 (±60s of jitter).

After three failed attempts we stop trying that specific event. The destination stays active and keeps receiving new events normally — you’ll just see this delivery marked Dead in the dashboard.

Auto-disable safety net. If a destination piles up 50 consecutive failed deliveries, we automatically disable it so we don’t keep pounding on a broken endpoint. You’ll see Auto-disabled on the row with a short reason. Once you’ve fixed the issue, re-enable it from the row’s expanded view.

Idempotency

The same event.id can arrive more than once — replays, retries that succeed late, network races. Your handler must be idempotent:

Dedupe on id (e.g., insert into a processed_events table with a unique constraint and ignore conflicts).
Don’t trust delivery order; events for the same resource can interleave.

Test mode

The Send test event button on each destination row fires a canned event with livemode: false, shaped exactly like a real event of the destination’s subscribed event type: an earnings destination gets an earnings.created test, an insider destination gets an insider-shaped test. If your handler parses the test event, it parses real events. Test events are delivered only to the destination you fired them from, and are throttled to 1 per minute per destination.

Security

HTTPS only. We refuse to deliver to plain http:// URLs in production.
SSRF defense. We resolve your URL’s IP at every delivery attempt and reject private (RFC 1918), loopback, link-local, and metadata-service ranges.
Signing-secret rotation. Use Regenerate secret on the destination’s row whenever you suspect a leak. The old secret stops working as soon as you rotate, so deploy the new secret to your handler in lockstep.
Secret access. Re-copy your secret from the destination’s row in the dashboard if you misplace it. Retrieval is gated by your dashboard login; API keys cannot read signing secrets.

Limits

5 active destinations per account. Disable or delete unused ones to free up slots.
A destination can subscribe to any combination of event types — one endpoint can receive everything.

Troubleshooting

Destination keeps auto-disabling. Open the destination’s expanded row and check Recent failures. Your endpoint is probably 5xx-ing or timing out beyond 10s. The fastest debug path is replaying a recent failed delivery from Recent events and inspecting the response body that came back. Signature verification fails. Three usual suspects:

You parsed the body before computing the HMAC. Always verify the raw bytes.
The signing secret in your config is stale after a rotation. Re-copy from the dashboard.
Your server has clock drift > 5 minutes. We reject signatures outside the skew window.

No events arrive at all. Confirm the destination is Active (not Disabled). Fire a test event from the row’s ⋯ menu — if that doesn’t arrive within ~5 seconds, the destination URL is unreachable from our network (check firewalls / IP allowlists). Still stuck? Open a ticket via Support and include the destination id + a recent event id from the dashboard.

Next steps

How to set up webhooks — step-by-step walkthrough with a working Python receiver.
Open the Webhooks dashboard to create your first destination.

Overview

Integrations

Datasets

Guides

Overview

How it works

Production checklist

Event types

Payload format

Envelope

`earnings.created` resource

Multiple events per earnings period

Financial statement resources

Earnings intelligence resources

`insider_trades.created` resource

`insider_ownership.created` resource

Headers

Verifying the signature

Retries

Idempotency

Test mode

Security

Limits

Troubleshooting

Next steps

​Overview

​How it works

​Production checklist

​Event types

​Payload format

​Envelope

​earnings.created resource

​Multiple events per earnings period

​Financial statement resources

​Earnings intelligence resources

​insider_trades.created resource

​insider_ownership.created resource

​Headers

​Verifying the signature

​Retries

​Idempotency

​Test mode

​Security

​Limits

​Troubleshooting

​Next steps

Overview

How it works

Production checklist

Event types

Payload format

Envelope

`earnings.created` resource

Multiple events per earnings period

Financial statement resources

Earnings intelligence resources

`insider_trades.created` resource

`insider_ownership.created` resource

Headers

Verifying the signature

Retries

Idempotency

Test mode

Security

Limits

Troubleshooting

Next steps