---
title: "Receive and verify Narwhal webhooks | Narwhal API"
description: "Create a Narwhal webhook destination, verify delivery signatures, handle duplicate events, and use history or the events journal to recover missed events."
url: "https://narwhalapi.com/how-to/receive-webhooks"
---

# Receive Narwhal webhooks

Create a webhook destination with your HTTPS URL, the countries and families you want, then verify the signature of every delivery before you trust it. Every account can keep up to 25 destinations, and each delivery costs one call.

## Create a destination and receive deliveries

Narwhal uses one account and one API key across its data APIs. REST and MCP share that key. Keep it in the `NARWHAL_API_KEY` environment variable and send it as `Authorization: Bearer YOUR_KEY` to `https://api.narwhalapi.com`.

1. **Create the destination** Send your HTTPS URL, country codes and family slugs to `POST /v1/webhooks/destinations`. The URL can contain up to 2,048 characters; choose 1 to 60 alpha-3 country codes or `WLD`, and 1 to 8 family slugs: `gdp`, `prices`, `labour`, `trade`, `policy_rate`, `yield_curve`, `predictions` and `filings`. A family not in that list is refused, and the error names the accepted ones. The request can also include `enabled: true`. The curl request selects `USA` and `MEX` with the `prices` and `labour` families. Replace its example HTTPS URL with the URL where your receiver accepts deliveries. Create a webhook destination

```
curl -s -X POST https://api.narwhalapi.com/v1/webhooks/destinations \
  -H "Authorization: Bearer $NARWHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/narwhal",
       "countries":["USA","MEX"],"families":["prices","labour"]}'
```

2. **Save the destination secret** The response includes `destination_id` and a `secret`, which is shown only once. Set `NARWHAL_WEBHOOK_SECRET` to that secret for the receiver. Keep the destination ID for requests that address this destination, including the test-delivery request. Use the returned secret to compute delivery signatures; the API key stays in the authorization header for your API requests. A secret returned by `rotate-secret` is also shown only once; for 24 hours after rotation, the signature header carries a second value signed with the old secret.
3. **Verify signatures before acting** Use the receiver below to compare signatures in constant time and reject timestamps older than five minutes. Accept a delivery if any signature value matches. The Python SDK also has a verifier at `from narwhalapi.webhooks import verify`. Return a 2xx quickly and do the work after. Python (Flask), a receiver that verifies the signature

```
import hashlib, hmac, json, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ[
    "NARWHAL_WEBHOOK_SECRET"
]  # returned once when you create the destination
seen = set()  # use a database table in production

@app.post("/narwhal")
def narwhal():
    raw = request.get_data()  # exact bytes, before any JSON parsing
    stamp = request.headers.get("x-narwhal-timestamp", "")
    if not stamp.isdigit() or abs(time.time() - int(stamp)) > 300:
        abort(400)  # missing, or older than five minutes
    expected = (
        hmac.new(SECRET.encode(), f"{stamp}.".encode() + raw, hashlib.sha256)
        .hexdigest()
        .encode()
    )
    header = request.headers.get("x-narwhal-signature", "")
    sent = [part.strip().removeprefix("sha256=").encode() for part in header.split(",")]
    if not any(hmac.compare_digest(expected, candidate) for candidate in sent):
        abort(401)  # a missing or malformed header lands here, not in a 500
    try:
        event = json.loads(raw)
    except ValueError:
        abort(400)
    if not isinstance(event, dict):
        abort(400)
    if event.get("event_id") in seen:  # retries and replays repeat the same event_id
        return "", 200
    seen.add(event.get("event_id"))
    print(event.get("type"), event.get("country"), event.get("family"))
    return "", 200
```

4. **Request a test delivery** Call `POST /v1/webhooks/destinations/{destination_id}/test` with the saved destination ID. A test delivery has `is_test: true`, no cursor, and no `release` or `data`. Delivery states are `pending`, `leased`, `succeeded`, `failed` and `cancelled`. Creating a destination beyond the limit returns `409 limit_reached`.

The receiver returns 400 for a missing or invalid timestamp and for a body that cannot be parsed as a JSON object. A missing or malformed signature returns 401. Once the signature comparison succeeds, the receiver parses the body before reading its event fields and recording the event ID.

Changing a monitor's URL keeps deliveries that are still waiting and sends them to the new URL. Changing its countries or types cancels only the waiting deliveries that no longer match.

## Event types and fields

Every event body has `schema_version`, `event_id`, `cursor`, `type`, `country` and `recorded_at`. A field with no value is left out. Choose the handler from `type`. Drop repeats by `event_id`, which is the same on every retry and replay.

| Event type | Sent when | Other fields |
| --- | --- | --- |
| `dataset.published` | A data series publishes a new figure, a period newer than its latest before | `family`, `resource_id`, `resource_version`, `operation`, `data` |
| `yield_curve.published` | A yield curve publishes a curve for a new date | `family`, `resource_id`, `resource_version`, `operation`, `data` |
| `release.updated` | A calendar release carries a figure it did not carry before | `family`, `resource_version`, `release_id`, `release`; `operation` and `data` when the values are known |
| `rate_decision.published` | A central bank announces a rate decision, once per meeting | `family`, `resource_id`, `resource_version`, `decision` |
| `prediction.event.closed`, `prediction.event.settled`, `prediction.event.voided` | A prediction market closes, settles or is voided | `prediction` |
| `filing.published` | A company files with its regulator | `filing` |

A monitor sends a delivery only when a new figure arrives. A release with no figure yet is not sent. A figure changed later is not sent and not charged, and still appears in `GET /v1/events` as `dataset.revised` and `yield_curve.revised`. A revised rate decision, a date change and a cancelled release are not sent either: read date changes from the calendar. A monitor fires only for releases Narwhal has for that country.

`data` holds the fields of the latest endpoint for `operation`. `release` holds the calendar fields of the release, with its indicators. `decision` holds the decision as the rate decisions endpoint serves it. `filing` holds the filing.

A `prices` event carries `year_over_year` and, where the stream has it, `month_over_month`, for the same period as the level. A `gdp` event carries growth next to the level, and always carries `annualized` and `seasonal_adjustment`. Every time in `release` is UTC and ends in `Z`.

A release day can produce a calendar event and a data event for one publication, matched by the release's reference period. A destination that matches both gets one delivery and pays for one: whichever carries the figure first. The other is not sent to that destination. A destination that matches only one of the two gets that one. Yield curves, rate decisions, filings and predictions are never folded into another event.

A rate meeting gives one delivery. For a country whose central bank Narwhal reads, it is `rate_decision.published`, and that country's calendar releases are not sent. For a `policy_rate` country that has calendar releases and no bank reader, it is the first `release.updated` of the meeting that carries the rate. A revised rate decision is not sent.

These examples come from production records: the Malaysian labour force survey for September 2026, the Federal Reserve decision of 28 October 2026 and a 10-K filed on 10 November 2026. The event ids and cursors of the last two are made up, because no such event has been sent yet.

Data event with `data`

```
{
  "schema_version": "1",
  "event_id": "8c9be1d1-85de-4ac7-9159-af741c8c30f3",
  "cursor": "984",
  "type": "dataset.published",
  "country": "MYS",
  "family": "labour",
  "resource_id": "00000000-0000-4000-8000-000000000533",
  "resource_version": "06f3cb03-af10-42ad-ad6a-91ea35cd5d02",
  "recorded_at": "2026-11-11T04:30:06Z",
  "operation": "economics_get_unemployment",
  "data": {
    "rate": "3.0",
    "period": "2026-09",
    "country": "MYS",
    "released_on": "2026-11-11"
  }
}
```

Release event with `release` and `data`

```
{
  "schema_version": "1",
  "event_id": "15fdc358-935b-4694-bf6a-4779e1bfc7e0",
  "cursor": "985",
  "type": "release.updated",
  "country": "MYS",
  "family": "labour",
  "resource_version": "ab144b21-82db-438b-9c38-9b79332923bf",
  "release_id": "9da56859-ff85-4d7b-b44f-fe3c2534cc31",
  "recorded_at": "2026-11-11T05:04:07Z",
  "operation": "economics_get_unemployment",
  "data": {
    "rate": "3.0",
    "period": "2026-09",
    "country": "MYS",
    "released_on": "2026-11-11"
  },
  "release": {
    "title": "Labour Force Survey: Sep 2026",
    "status": "published",
    "schedule": {
      "at": "2026-11-11T04:00:00Z",
      "timezone": "Asia/Kuala_Lumpur",
      "precision": "exact",
      "time_basis": "calendar"
    },
    "indicators": [
      {
        "unit": "percent",
        "title": "Labour force participation rate, seasonally adjusted",
        "actual": "71.0",
        "period": "2026-09",
        "measure": "participation_rate",
        "previous": "71.0",
        "actual_as_of": "2026-11-11T04:00:00Z",
        "value_status": "available",
        "previous_as_of": "2026-11-11T04:00:00Z",
        "transformation": "level",
        "previous_period": "2026-08",
        "seasonal_adjustment": "seasonally_adjusted"
      },
      {
        "unit": "percent",
        "title": "Unemployment rate, seasonally adjusted",
        "actual": "3.0",
        "period": "2026-09",
        "measure": "unemployment_rate",
        "previous": "2.9",
        "actual_as_of": "2026-11-11T04:00:00Z",
        "value_status": "available",
        "previous_as_of": "2026-11-11T04:00:00Z",
        "transformation": "level",
        "previous_period": "2026-08",
        "seasonal_adjustment": "seasonally_adjusted"
      }
    ],
    "reference_period": "2026-09",
    "officially_published_at": "2026-11-11T04:00:00Z"
  }
}
```

Rate decision event

```
{
  "schema_version": "1",
  "event_id": "3f0c7d52-8a1e-4b6f-9d2a-5c41e7b0a9d6",
  "cursor": "986",
  "type": "rate_decision.published",
  "country": "USA",
  "family": "policy_rate",
  "resource_id": "1b0f5b3e-6c1a-4d0e-8f27-3a9d5e6c7b10",
  "resource_version": "9c2e4a7d-1f3b-4e58-a6d0-72b8c1e5f934",
  "recorded_at": "2026-10-28T19:05:41Z",
  "decision": {
    "rates": [
      {
        "rate": null,
        "role": "main",
        "lower_bound": "3.75",
        "rate_source": "stated",
        "upper_bound": "4.00",
        "instrument_label": "target range for the federal funds rate"
      }
    ],
    "action": "hold",
    "quotes": [
      {
        "url": "https://www.federalreserve.gov/newsevents/pressreleases/monetary20261028a.htm",
        "text": "The Committee decided to maintain the target range for the federal funds rate at 3-3/4 to 4 percent"
      }
    ],
    "country": "USA",
    "currency": null,
    "authority": "Federal Reserve System",
    "date_basis": "decision",
    "decided_on": "2026-10-28",
    "from_union": null,
    "decision_id": "e5149a43bf24f96d202a6a8a6700d12b",
    "source_tier": "own",
    "announced_on": null,
    "authority_id": "federal_reserve",
    "effective_on": null,
    "served_state": "confirmed",
    "votes_status": "unknown",
    "evidence_kind": "statement",
    "any_rate_moved": false,
    "decision_basis": "committee",
    "unchanged_since": null,
    "source_publisher": null,
    "source_published_on": null
  }
}
```

Filing event

```
{
  "schema_version": "1",
  "event_id": "a7e19b04-52cd-4f38-8b6e-0d41c9f27e53",
  "cursor": "987",
  "type": "filing.published",
  "country": "USA",
  "recorded_at": "2026-11-10T22:24:05Z",
  "filing": {
    "fp": "FY",
    "fy": 2026,
    "url": "https://www.sec.gov/Archives/edgar/data/1829311/000162828026072846/0001628280-26-072846-index.htm",
    "form": "10-K",
    "type": "annual",
    "title": "10-K",
    "filed_at": "2026-11-10T22:23:39Z",
    "filing_id": "0001628280-26-072846",
    "company_id": "usa:0001829311",
    "period_end": "2026-08-31",
    "company_name": "BITMINE IMMERSION TECHNOLOGIES, INC."
  }
}
```

An app sign-in, such as a Claude or ChatGPT connector, cannot create or manage destinations. An API key can.

## Get new filings for companies you follow

Add the `filings` family and a `companies` list to the destination. Narwhal then sends a `filing.published` event each time one of those companies files. For a 13D or 13G stake filing, it also sends one when a listed company is the company the stake is in. Each account can watch up to 1,000 companies.

Watch Apple's filings

```
curl -s -X POST https://api.narwhalapi.com/v1/webhooks/destinations \
  -H "Authorization: Bearer $NARWHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/narwhal","countries":["USA"],
       "families":["filings"],"companies":["usa:0000320193"]}'
```

Companies use the Filings API's `company_id`, such as `usa:0000320193` for Apple. The `companies` list is required with the `filings` family and refused without it. An unknown company returns 400 and names the ids it could not find. The request still needs `countries`, but countries do not narrow filings.

Filing event payload

```
{
  "schema_version": "1",
  "event_id": "a7e19b04-52cd-4f38-8b6e-0d41c9f27e53",
  "cursor": "987",
  "type": "filing.published",
  "country": "USA",
  "recorded_at": "2026-11-10T22:24:05Z",
  "filing": {
    "fp": "FY",
    "fy": 2026,
    "url": "https://www.sec.gov/Archives/edgar/data/1829311/000162828026072846/0001628280-26-072846-index.htm",
    "form": "10-K",
    "type": "annual",
    "title": "10-K",
    "filed_at": "2026-11-10T22:23:39Z",
    "filing_id": "0001628280-26-072846",
    "company_id": "usa:0001829311",
    "period_end": "2026-08-31",
    "company_name": "BITMINE IMMERSION TECHNOLOGIES, INC."
  }
}
```

Use `filing.filing_id` to fetch the filing from the Filings API. `fy`, `fp` and `period_end` are left out when a filing has none, as with most event and ownership filings.

## Receive webhooks without code

A Zapier Catch Hook, Make Custom webhook or n8n Webhook node can supply the destination URL. Put that URL in the destination's `url` field and choose the countries and families for the flow. Keep the catch-hook URL secret: these no-code destinations do not verify the Narwhal signature for you.

Signature verification needs code such as the Python receiver above. If you need that verification, use the receiver for incoming deliveries. The [webhook reference](https://narwhalapi.com/docs/api/webhooks.md) has the destination, delivery history and replay operations; the [events reference](https://narwhalapi.com/docs/api/events.md) describes the REST journal for reading events from a cursor.

## Choose a receiver or polling

| Situation | Best option | Why |
| --- | --- | --- |
| A service of your own | The Python receiver | It verifies the signature and handles repeated event IDs |
| A no-code flow | A Zapier, Make or n8n catch hook | It supplies a destination URL; keep that URL secret |
| Polling instead of deliveries | GET /v1/events or the economic calendar | The journal works from a cursor; the calendar covers dates |

## Why verify the raw webhook body?

The signature covers the exact bytes of the body, so parsing and re-serialising it changes what you compare. Read `x-narwhal-timestamp` as Unix seconds and join its value, a period and the raw body. Compute the lowercase hex HMAC-SHA256 with the secret encoded as UTF-8.

The `x-narwhal-signature` header holds `sha256=<hex>`. Compare the computed value with the supplied signature in constant time before parsing the JSON, as the receiver does.

## What if my webhook server was down?

Deliveries retry, and the delivery history lets you see failures and replay a delivery. Use `GET .../deliveries` for the destination's history, then `POST .../deliveries/{delivery_id}/replay` for the delivery you want to receive again. A replay repeats the same event.

To catch up from a saved position, read `GET /v1/events` from your last cursor. Keep that cursor for the journal path; the test-delivery operation does not supply one.

## Can I receive the same event twice?

Yes, retries and replays repeat the same `event_id`. Use it as the idempotency key and store it before acting on the event. In production, use a database table for stored IDs, as the receiver's comment indicates.

The example receiver keeps IDs in `seen`. When an ID is already present, it returns 200 without printing the event again. For an unseen ID, it adds the ID before printing the event's type, country and family.

## Worked example: receive one delivery

For the event recorded at `2026-09-25T15:44:56Z`, the payload identifies `dataset.published`, country `MEX` and family `labour`. It also carries the schema version, event ID, cursor, resource ID and resource version.

Economics event payload

```
{
  "schema_version": "1",
  "event_id": "...",
  "cursor": "1",
  "type": "dataset.published",
  "country": "MEX",
  "family": "labour",
  "resource_id": "...",
  "resource_version": "...",
  "recorded_at": "2026-09-25T15:44:56Z"
}
```

The delivery arrives with the timestamp and signature headers. The receiver reads the timestamp and requires an age under 300 seconds, then recomputes the HMAC of `<timestamp>.<body>`. After a signature matches, it parses the payload and looks up `event_id`. For an unseen event, it stores the ID and prints the fields below before returning 200.

Receiver output

```
dataset.published MEX labour
```

Published 26 October 2026.

## Next steps

- [API reference Webhook API reference](https://narwhalapi.com/docs/api/webhooks.md)
- [API reference Events journal reference](https://narwhalapi.com/docs/api/events.md)
- [How-to Get an alert before an economic release](https://narwhalapi.com/how-to/get-an-alert-before-an-economic-release.md)
- [How-to Stream live events](https://narwhalapi.com/how-to/stream-live-data.md)
- [APIs List of APIs](https://narwhalapi.com/api.md)

## How-to guides

- [Stream live events over a WebSocket](https://narwhalapi.com/how-to/stream-live-data.md)
- [Cache responses and handle 429 errors](https://narwhalapi.com/how-to/cache-responses-and-handle-429-errors.md)
- [Backfill historical data](https://narwhalapi.com/how-to/backfill-historical-data.md)
- [Schedule a daily data pull](https://narwhalapi.com/how-to/schedule-a-daily-data-pull.md)
- [Give an LLM agent access to Narwhal](https://narwhalapi.com/how-to/give-an-llm-agent-access-to-narwhal.md)
- [All how-to guides](https://narwhalapi.com/how-to.md)

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)
