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.

Example event payload

{
  "context": {
    "companyId": "42"
  },
  "eventTimestamp": "2025-04-29T16:15:30.456789",
  "eventType": {
    "value": "job_state_change"
  },
  "idempotencyKey": {
    "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "payload": {
    "value": {
      "jobId": "d35a12c1-7a2f-46b9-8d60-9e0a2a84c205",
      "jobType": "materialize-view",
      "state": "completed"
    }
  }
}

Your endpoint should return a 2xx status code to acknowledge receipt.

Handling idempotency

Each event includes an idempotencyKey — a unique identifier for that specific delivery. If Narrative delivers the same event more than once (for example, due to a network retry), the idempotency key remains the same. Use the idempotency key to detect duplicates:

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

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

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

​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

Example event payload

Handling idempotency

Managing subscriptions

List all subscriptions

Get a specific subscription

Archive a subscription

Best practices

Related content