Subscribing to Notifications

Webhook subscriptions let you receive HTTP POST notifications when jobs change state, eliminating the need to poll the jobs API. This guide walks through creating, receiving, and managing webhook subscriptions.

For background on how webhooks work and when to use them, see Webhooks. For complete API details, see the Webhooks API Reference.

Prerequisites

An API token with Webhooks read and write permissions
An HTTPS endpoint ready to receive POST requests
Familiarity with job types and job states

What you’ll learn

How to create a job webhook subscription with filters
How to receive and verify webhook events
How to list, inspect, and archive subscriptions

Creating a job webhook subscription

Use the POST /webhooks endpoint to create a subscription. Set the type to webhook_subscription_jobs and provide your endpoint URL.

Receiving events

When a job matches your subscription’s filters, Narrative sends an HTTP POST to your URL with a JSON payload. The request carries Content-Type: application/json and an X-Narrative-Secret header.

Verify the request

Compare the X-Narrative-Secret header against the secret you stored when you created the subscription. Reject anything that does not match — that request did not come from Narrative.

Example event payload

Every delivery has the same four-field envelope. type tells you what data contains.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2025-04-29T16:14:02.900Z",
  "type": "job.completed",
  "data": {
    "job_id": "9a3cf334-4c6d-4d3f-a7d6-22b6e6f2ac1b",
    "type": "datasets_deliver_data",
    "state": "completed",
    "created_at": "2025-04-29T16:12:45.123456Z",
    "updated_at": "2025-04-29T16:14:02.900Z",
    "ended_at": "2025-04-29T16:14:02.900Z",
    "idempotency_key": "some-key",
    "input": {
      "dataset_id": 10736,
      "dataset_name": "my_dataset"
    },
    "result": { "rows": 1500 },
    "request_source": {
      "type": "api_user",
      "company_id": 42,
      "user_id": 1248
    }
  }
}

Return any 2xx status code to acknowledge receipt. Anything else — including a connection failure — is treated as a failed attempt and retried with exponential backoff until the event’s attempt budget runs out. For the full delivery payload schema and the list of type values, see Webhook Event Reference.

Handling idempotency

Each delivery envelope carries an id field. Retries of the same event reuse this id, so use it to make your handler idempotent.

When you receive an event, check if you’ve already processed that envelope id.
If yes, return 200 OK without processing again.
If no, process the event and store the id.

Managing subscriptions

List all subscriptions

curl https://api.narrative.io/webhooks \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Returns an array of all webhook subscriptions for your company, including both active and archived subscriptions.

Get a specific subscription

curl https://api.narrative.io/webhooks/{webhook_subscription_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Archive a subscription

Archiving stops event delivery but retains the subscription record.

curl -X DELETE https://api.narrative.io/webhooks/{webhook_subscription_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Archiving is permanent — there is no way to reactivate an archived subscription. Create a new subscription if you need to resume notifications.

Best practices

Practice	Why
Respond quickly	Return a `2xx` response immediately, then process the event asynchronously. Slow responses may cause delivery timeouts.
Store the secret	Save the `secret` from the creation response. You cannot retrieve it later.
Implement idempotency	Use the `idempotencyKey` to deduplicate events in case of retries.
Use HTTPS	Webhook URLs must use HTTPS to protect payloads in transit.
Filter narrowly	Subscribe only to the job types and states you need. This reduces noise and processing overhead.

Webhooks

How webhooks work and when to use them

Webhook Event Reference

Complete field reference for subscription requests and responses

Tracking Job Status

Poll-based alternative for monitoring job progress

API Keys

Create and manage API tokens for webhook access

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

What you’ll learn

Creating a job webhook subscription

Receiving events

Verify the request

Example event payload

Handling idempotency

Managing subscriptions

List all subscriptions

Get a specific subscription

Archive a subscription

Best practices

Webhooks

Webhook Event Reference

Tracking Job Status

API Keys

​Prerequisites

​What you’ll learn

​Creating a job webhook subscription

​Receiving events

​Verify the request

​Example event payload

​Handling idempotency

​Managing subscriptions

​List all subscriptions

​Get a specific subscription

​Archive a subscription

​Best practices

​Related content

Webhooks

Webhook Event Reference

Tracking Job Status

API Keys

Prerequisites

What you’ll learn

Creating a job webhook subscription

Receiving events

Verify the request

Example event payload

Handling idempotency

Managing subscriptions

List all subscriptions

Get a specific subscription

Archive a subscription

Best practices

Related content