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

# Webhooks

> Push notifications for real-time market events. Pro and Enterprise.

## 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, push records into your warehouse, or trigger downstream automation.

<Info>
  **New to webhooks?** The [setup guide](/guides/setup-webhooks) 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.
</Info>

## How it works

Five steps to get from zero to receiving events:

<Steps>
  <Step title="Create a destination">
    Register an HTTPS endpoint and the events you want to receive from the [Webhooks dashboard](https://financialdatasets.ai/webhooks).
  </Step>

  <Step title="Set up your endpoint">
    Stand up an HTTPS handler that can accept JSON POSTs and read the raw request body. See the [setup guide](/guides/setup-webhooks) for Python + Node examples.
  </Step>

  <Step title="Verify the signature">
    Confirm each request came from us using the `FD-Signature` header. See [Verifying the signature](#verifying-the-signature).
  </Step>

  <Step title="Test with a canned event">
    Fire a test event from the dashboard's destination row and confirm your endpoint returns `2xx` within 10 seconds.
  </Step>

  <Step title="Go live">
    Walk through the [production checklist](#production-checklist) before flipping real customer flows onto your handler.
  </Step>
</Steps>

<Note>
  Webhooks are available on **Pro** and **Enterprise** plans. [Manage your plan](https://financialdatasets.ai/billing/subscriptions) from the dashboard.
</Note>

## Production checklist

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

1. **Use HTTPS, not HTTP.** Your endpoint URL must start with `https://`. We won't deliver to plain `http://` in production. [Security →](#security)
2. **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 →](#verifying-the-signature)
3. **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 →](#retries-and-delivery-semantics)
4. **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 →](#idempotency)
5. **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 →](#security)

## 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/earnings/earnings) API response**. Any parser you've written against the Earnings API will work unchanged against the webhook payload.

See the [Earnings API reference](/api/earnings/earnings) 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:

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

### Multiple events per earnings period

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–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 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).

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

<Warning>
  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.
</Warning>

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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)
    ```
  </Tab>

  <Tab title="Node">
    ```js theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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)
    }
    ```
  </Tab>
</Tabs>

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.

<Warning>
  **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.
</Warning>

## 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`. Useful for confirming your signature verification + 2xx response path before flipping the switch on production data.

Test events 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.
* **One event type per destination** today. The picker is single-select for now; we'll widen to multi-select as we add more event types.

## 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:

1. You parsed the body before computing the HMAC. Always verify the raw bytes.
2. The signing secret in your config is stale after a rotation. Re-copy from the dashboard.
3. 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](/support) and include the destination id + a recent event id from the dashboard.

## Next steps

* [How to set up webhooks](/guides/setup-webhooks) — step-by-step walkthrough with a working Python receiver.
* [Open the Webhooks dashboard](https://financialdatasets.ai/webhooks) to create your first destination.