---
title: "Webhooks API Reference | Narwhal API"
description: "Read the Webhooks API reference for signed delivery, endpoint management and retries. Find details on webhook endpoints and retry behaviour."
url: "https://narwhalapi.com/docs/api/webhooks"
---

# Webhooks API reference

Signed at-least-once event delivery with history and replay

## Destinations

Ten authenticated routes create, list, inspect, update, rotate, test and delete destinations, plus read configuration and delivery history and replay one delivery. Destination filters remain inside the account's active country and family rights. Webhooks are available on every account. Each delivery costs one call at the price of the data it carries. An account can keep up to 25 destinations, enabled or not. At that point, `POST /v1/webhooks/destinations` returns `409` `limit_reached` until you delete one. The limit counts only enabled destinations.

`GET /v1/webhooks/destinations` `POST /v1/webhooks/destinations` `GET /v1/webhooks/destinations/{destination_id}` `PATCH /v1/webhooks/destinations/{destination_id}` `DELETE /v1/webhooks/destinations/{destination_id}` `POST /v1/webhooks/destinations/{destination_id}/test` `POST /v1/webhooks/destinations/{destination_id}/rotate-secret` `GET /v1/webhooks/destinations/{destination_id}/history` `GET /v1/webhooks/destinations/{destination_id}/deliveries` `POST /v1/webhooks/destinations/{destination_id}/deliveries/{delivery_id}/replay`

## Request fields

| Field | Type | Rule |
| --- | --- | --- |
| `url` | string | Required. An HTTPS URL of up to 2,048 characters. |
| `countries` | array of ISO 3166 alpha-3 codes | Required. 1–60 uppercase ISO alpha-3 codes, or `WLD`. |
| `families` | array of family slugs | Required. 1–8 of the families listed under Event types. A family not listed there is refused with an error that names the accepted ones. |
| `enabled` | boolean | Optional. Defaults to true. |

`PATCH` replaces the entire configuration: send `url`, `countries`, `families` and `enabled` every time. Leaving out `enabled` turns a disabled destination back on. `POST` and `PATCH` return `409 limit_reached` if enabling a destination would exceed the limit. Disable or delete another destination first.

## Destination fields

| Field | Type | Meaning |
| --- | --- | --- |
| `destination_id` | uuid | Identifies the destination. |
| `url` | string | The HTTPS receiver URL. |
| `countries` | array of ISO 3166 alpha-3 codes | Filters countries within the account's active rights. |
| `families` | array of family slugs | Filters by release family. |
| `enabled` | boolean | Indicates whether the destination is enabled. |
| `config_version` | integer | Increments on each configuration change; deliveries record the version they were sent under. |
| `secret_version` | integer | Increments on each secret rotation. |
| `created_at` | UTC timestamp | The time the destination was created. |
| `updated_at` | UTC timestamp | The time the destination was last updated. |
| `secret` | string | Returned only by create and rotate-secret; store it because it is not shown again. |
| `disabled_reason` | string | Why the destination is disabled: `customer` or `plan_limit`. Left out when the destination is enabled. |

DELETE and replay return `204 No Content`. Test returns `delivery_id` (left out when nothing was queued), `status` (`queued`, `rate_limited` or `disabled`) and `retry_after_seconds` when rate limited. The configuration history route returns `history`, with one entry per version containing `config_version`, `url`, `countries`, `families`, `enabled` and `recorded_at`. The list route returns `destinations` and `destination_limit`, the number of enabled destinations the plan allows. A field with no value, such as `disabled_reason` on an enabled destination, is left out. An unknown or deleted destination returns `404 webhook_request_failed` on every destination route. Replaying an unavailable delivery returns the same error. An invalid deliveries `cursor` returns `400`. `503 webhook_unavailable` means webhooks cannot be served right now. Test deliveries have an account-wide 10-second cooldown. During it, the test route returns `status: "rate_limited"` and `retry_after_seconds`.

## Deliveries

The deliveries route pages with `limit` (1–100, default 50) and `cursor`, and returns `next_cursor` (null on the last page).

| Field | Type | Meaning |
| --- | --- | --- |
| `delivery_id` | string | Identifies the delivery. |
| `event_cursor` | integer | Identifies the event; left out for test deliveries. |
| `is_test` | boolean | Sent as true only for a test delivery. |
| `config_version` | integer | The destination configuration version used for the delivery. |
| `state` | enum | The delivery state: `pending`, `leased`, `succeeded`, `failed` or `cancelled`. |
| `attempts` | integer | The number of delivery attempts. |
| `replays` | integer | The number of replays; sent only when greater than 0. |
| `next_attempt_at` | timestamp | The time of the next attempt; sent only while the state is `pending` or `leased`. |
| `retry_until` | timestamp | The time until which the delivery can be retried; sent only while the state is `pending` or `leased`. |
| `last_status` | integer | The receiver's last HTTP status; left out before the first attempt. |
| `last_error` | string | The last error; left out when there is none. |
| `created_at` | timestamp | The time the delivery was created. |
| `updated_at` | timestamp | The time the delivery was last updated. |

## Event types

A destination receives the event types below when its subscribed families match, within the account's active country and family rights.

A destination subscribes to one or more families: `gdp`, `prices`, `labour`, `trade`, `policy_rate`, `yield_curve`, `predictions` and `filings`.

| Event type | Meaning |
| --- | --- |
| `release.updated` | When a calendar release carries a figure it did not carry before |
| `dataset.published` | When an accepted official publication adds a new reference period |
| `yield_curve.published` | When a new yield-curve date is accepted |
| `rate_decision.published` | When a central bank announces a rate decision, once per meeting |

A destination receives a delivery only when a new figure arrives. A date change, a cancelled release and a figure changed later are not sent. Read date changes from the calendar.

## Prediction events

Destinations with the `predictions` family receive `prediction.event.closed` when event trading stops, `prediction.event.settled` when the event settles and `prediction.event.voided` when it is voided. We send each at most once per event. The body contains the event's status, never a probability or winning outcome. The market ID is `prediction_event_id`; `event_id` identifies the event.

## Payload bodies

Webhook bodies carry `schema_version`; REST events do not. A field with no value is left out. `cursor` orders journal events.

Economics and release event

```
{
  "schema_version": "1",
  "event_id": "2cdf117d-4a23-4a1f-b68e-93a7e9dc765e",
  "cursor": "1",
  "type": "dataset.published",
  "country": "MEX",
  "family": "labour",
  "resource_id": "775d11a3-a6de-52b1-b41b-a236ad595e7a",
  "resource_version": "822e107c-09f6-4736-82e9-082d725398a2",
  "recorded_at": "2026-09-25T15:44:56Z"
}
```

Release events carry `release_id` instead of `resource_id`.

Prediction event

```
{
  "schema_version": "1",
  "event_id": "5d0b6f0e-7a1c-4c53-9b5e-2f9c4b1d8a63",
  "cursor": "470",
  "type": "prediction.event.settled",
  "country": "USA",
  "recorded_at": "2026-10-28T20:15:02Z",
  "prediction": {
    "prediction_event_id": "usa-fed-2026-10",
    "topic_id": "usa-fed",
    "shape": "scalar",
    "status": "settled",
    "closes_at": "2026-10-28T17:59:00Z",
    "resolves_at": "2026-10-28T18:00:00Z",
    "settlements": [
      {
        "venue": "kalshi",
        "status": "settled"
      },
      {
        "venue": "polymarket",
        "status": "settled"
      }
    ],
    "release_id": "ae2a77cc-3b5b-4541-a060-3bc2ea1145d9"
  }
}
```

Test delivery

```
{
  "schema_version": "1",
  "event_id": "9f1c2a54-3b7d-4e0a-8c46-1d5e7b9a0f32",
  "type": "webhook.test",
  "recorded_at": "2026-10-22T09:00:00Z"
}
```

A test delivery has no `cursor`, no `release` and no `data`.

## Signatures and retries

1. Read `x-narwhal-timestamp` (Unix seconds) and the raw request body before parsing any JSON.
2. Compute the lowercase hex HMAC-SHA256 of `timestamp + "." + raw_body`, keyed with the destination `secret` as UTF-8 bytes.
3. Compare the result in constant time with each `sha256=<hex>` value in `x-narwhal-signature`. Accept the delivery if any value matches. For 24 hours after a secret rotation, the header carries a second value, signed with the previous secret.
4. Reject timestamps too far from your clock, such as those older than five minutes, to prevent replays.

Delivery is at least once. Return a 2xx response only after durable processing; the response body is ignored. `event_id` identifies the event and is the deduplication key across retries and replays. `delivery_id` identifies a delivery attempt; retries keep it, and test deliveries reuse it as `event_id`.

A 429 or 5xx response, a timeout or a connection error is retried with exponential backoff, up to one hour between attempts, and longer when a 429 or 503 sends `Retry-After`. A redirect or any other status fails the delivery. The retry window is 24 hours from delivery creation or the latest replay.

## History and replay

Delivery history records attempt state and response status. Replay creates a new delivery for the same immutable event. Secret rotation has a 24-hour overlap window so receivers can validate either signature.

Was this page helpful?
