Webhook Event Reference

This reference documents the wire format for webhook subscriptions and the events Narrative delivers. For a conceptual overview, see Webhooks. For step-by-step usage, see Subscribing to Notifications. All field names in requests, responses, and delivery payloads use snake_case.

Subscription response fields

GET /webhooks and GET /webhooks/{id} return this shape. POST /webhooks returns the same shape with secret populated.

Field	Type	Required	Description
`id`	string (UUID)	Yes	Unique identifier for the subscription.
`app_id`	integer or null	No	The app this subscription follows. `null` on job subscriptions.
`name`	string or null	No	The label supplied at creation time. `null` if none was given.
`secret`	string (UUID)	Yes	Sent back on every delivery in the `X-Narrative-Secret` header. Compare it against this value to confirm a callback came from Narrative.
`status`	string	Yes	`active` or `archived`. Read endpoints only return active subscriptions; an archived subscription responds `404`.
`company_id`	integer	Yes	The company that owns the subscription.
`job_ids`	object or null	No	The `job_ids` filter wrapped as `{ "values": [...] }`, or `null` if the subscription does not filter by job.
`job_states`	object or null	No	The `states` filter wrapped as `{ "values": [...] }`, or `null` if the subscription does not filter by state.
`job_types`	object or null	No	The `job_types` filter wrapped as `{ "values": [...] }`, or `null` if the subscription does not filter by type.
`url`	string (URI)	Yes	The endpoint events are delivered to.
`created_at`	string	Yes	Local ISO 8601 date-time with no offset (`2025-04-29T16:12:45.123456`). Read it as UTC.
`updated_at`	string	Yes	Same format as `created_at`.

The three job filters are objects, not bare arrays, on responses. Requests take the bare array form (see below) and the server wraps them for retrieval.

Example response (job subscription with all three filters set):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "app_id": null,
  "name": "job_updates",
  "secret": "8b6dba8c-9a8b-4a3a-8469-9dc7a33c3e17",
  "status": "active",
  "company_id": 42,
  "job_ids": {
    "values": [
      "9a3cf334-4c6d-4d3f-a7d6-22b6e6f2ac1b",
      "d35a12c1-7a2f-46b9-8d60-9e0a2a84c205"
    ]
  },
  "job_states": { "values": ["completed", "failed"] },
  "job_types": { "values": ["datasets_deliver_data", "materialize-view"] },
  "url": "https://webhooks.mycompany.com/events",
  "created_at": "2025-04-29T16:12:45.123456",
  "updated_at": "2025-04-29T16:12:45.123456"
}

Example response (app subscription):

{
  "id": "6b0d0f0a-2c4e-4b6a-9c1d-3e5f7a9b1c3d",
  "app_id": 1234,
  "name": null,
  "secret": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "status": "active",
  "company_id": 42,
  "job_ids": null,
  "job_states": null,
  "job_types": null,
  "url": "https://webhooks.mycompany.com/app-events",
  "created_at": "2025-04-29T16:12:45.123456",
  "updated_at": "2025-04-29T16:12:45.123456"
}

Create request fields

POST /webhooks accepts one of two request shapes, chosen by type.

Job subscription

Field	Type	Required	Description
`type`	string	Yes	Must be `webhook_subscription_jobs`.
`url`	string (URI)	Yes	HTTPS endpoint to receive events.
`name`	string or null	No	A label for your own use. Narrative does not interpret it.
`job_ids`	array of strings (UUID) or null	No	Only deliver events for these jobs. Omit to match any job.
`job_types`	array of strings or null	No	Only deliver events for these job types. Each value is at most 255 characters. Omit to match any type.
`states`	array of strings or null	No	Only deliver events when a job enters one of these states. Omit to match any state.

Filters combine with AND: an event is delivered only if it satisfies every filter you set. Omitting all three receives every job event for your company. Example request:

{
  "type": "webhook_subscription_jobs",
  "url": "https://your-app.example.com/webhooks/narrative",
  "name": "failed_job_alerts",
  "job_types": ["materialize-view", "datasets_deliver_data"],
  "states": ["failed"]
}

App subscription

Field	Type	Required	Description
`type`	string	Yes	Must be `webhook_subscription_app`.
`app_id`	integer	Yes	The app whose events you want. Numeric app id, not a UUID.
`url`	string (URI)	Yes	HTTPS endpoint to receive events.
`name`	string or null	No	A label for your own use. Narrative does not interpret it.

Job events are never delivered to an app subscription. Example request:

{
  "type": "webhook_subscription_app",
  "app_id": 1234,
  "url": "https://webhooks.mycompany.com/app-events",
  "name": "app_events"
}

Delivery payload

This is the request Narrative POSTs to your url. Verify the X-Narrative-Secret header against the subscription’s secret before processing the body. Every delivery has the same four-field envelope; type tells you what data contains.

Field	Type	Required	Description
`id`	string (UUID)	Yes	Unique per delivery attempt-group. Retries reuse this id — key your idempotency store on it.
`created_at`	string (date-time)	Yes	When the event was queued. RFC 3339 with a `Z` offset. Different format from the subscription’s `created_at`, which has no offset.
`type`	string	Yes	`job.<state>` for job events; `<app_name>.<event_type>` for app events.
`data`	object	Yes	`JobEventData` when `type` starts with `job.`, otherwise the app event payload.

`type` values

Job events use job.<state>:

job.pending
job.scheduled
job.running
job.completed
job.pending_cancellation
job.cancelled
job.failed

App events use <app_name>.<event_type>. The app name is lowercased with a leading “the” dropped, punctuation removed, and spaces replaced with underscores. An app named “My Test App” reporting s3_delivery.completed produces my_test_app.s3_delivery.completed.

Job event `data` fields

For type starting with job., data is a snapshot of the job at the moment it entered the state, plus a few resolved names.

Field	Type	Required	Description
`job_id`	string (UUID)	Yes	The job.
`type`	string	Yes	The job type, e.g. `datasets_deliver_data`.
`state`	string	Yes	The state the job just entered. See Job states.
`created_at`	string (date-time)	Yes	When the job was created. RFC 3339.
`updated_at`	string (date-time)	Yes	When the job last changed.
`ended_at`	string (date-time) or null	No	When the job reached a terminal state. `null` while it is still running.
`dequeued_at`	string (date-time) or null	No	When a worker took the job off the queue. `null` while it is still queued.
`data_plane_id`	string (UUID) or null	No	The data plane the job ran on. `null` for jobs not pinned to one.
`data_plane_name`	string	No	Display name for `data_plane_id`. Only present when the data plane still exists.
`executor`	string or null	No	The internal executor that picked the job up. `null` until one does.
`idempotency_key`	string	Yes	The job’s own idempotency key. Distinct from the envelope `id`.
`input`	object	Yes	The job’s input as submitted. Narrative adds `dataset_name` when the input names a dataset, and strips `compiled_select`, `snowflake_create_table`, and `snowflake_insert_statement`, which hold generated SQL.
`result`	object or null	No	The job’s result. `null` until it completes.
`request_source`	object	Yes	Who or what asked for the job. See below.

request_source fields:

Field	Type	Required	Description
`type`	string	Yes	e.g. `api_user`, `process`.
`company_id`	integer	No
`user_id`	integer	No
`company_name`	string	No	Display name for `company_id`. Only present when the company still exists.
`user_name`	string	No	Display name for `user_id`. Only present when the user still exists.

Example job event:

{
  "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",
    "dequeued_at": "2025-04-29T16:12:50Z",
    "data_plane_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
    "data_plane_name": "us-east-1 production",
    "executor": null,
    "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,
      "company_name": "My Company",
      "user_name": "[email protected]"
    }
  }
}

Example app event:

{
  "id": "0b1f6f8e-9a7c-4f7b-9a51-2f4f1f9a3c21",
  "created_at": "2025-04-29T16:14:02.900Z",
  "type": "my_test_app.s3_delivery.completed",
  "data": {
    "company_id": 42,
    "connection_id": "f79cbdae-4848-47ca-95e8-69588364d185",
    "app_name": "My Test App",
    "dataset": {
      "id": 10736,
      "name": "my_dataset",
      "display_name": "My Dataset"
    },
    "profile": {
      "id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
      "name": "default"
    },
    "rows_delivered": 1500
  }
}

App payloads are app-defined beyond the fields Narrative adds. Consult the app’s documentation for the full shape.

Verifying deliveries

Every delivery carries an X-Narrative-Secret header. Compare it against the secret you stored when you created the subscription and reject anything that does not match. Return any 2xx to acknowledge the event. 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. Make your handler idempotent on the envelope’s id.

Job types

The job_types filter is an open string, not a closed enum. New job types are added as the platform grows, so no fixed list is authoritative. Common values include:

datasets_deliver_data
datasets_sample
datasets_calculate_column_stats
datasets_delete_table
materialize-view
model_training_run
model_inference_run
nql-forecast

Each value is a string up to 255 characters. For descriptions, see Job Types.

Job states

The states filter accepts these values.

Value	Description
`pending`	Job is queued and waiting for execution.
`scheduled`	Job has been claimed for execution and is being handed off to an executor.
`running`	Job is currently being executed.
`completed`	Job finished successfully.
`pending_cancellation`	Job is marked for cancellation but still running.
`cancelled`	Job was cancelled before completion.
`failed`	Job execution failed.

For state transitions, see Tracking Job Status.

Subscription status values

Value	Description
`active`	Subscription is live and receiving events.
`archived`	Subscription is disabled and no longer receives events. Read endpoints exclude archived subscriptions.

API endpoints

Method	Path	Description
`GET`	`/webhooks`	List all webhook subscriptions
`POST`	`/webhooks`	Create a webhook subscription
`GET`	`/webhooks/{webhook_subscription_id}`	Get a subscription by ID
`DELETE`	`/webhooks/{webhook_subscription_id}`	Archive a subscription

Webhooks

How webhooks work and when to use them

Subscribing to Notifications

Step-by-step guide to creating and managing subscriptions

Job Types

Detailed descriptions of common job types

Webhooks API

Full REST API documentation for webhook endpoints

Overview

Connectors

Integrations

Workflow Reference

Webhook Reference

Security Reference

Architecture Reference

Error Reference

Deprecations

Model Inference Reference

Rosetta Stone Reference

UI Reference

SDKs

Glossary

Billing

Subscription response fields

Create request fields

Job subscription

App subscription

Delivery payload

`type` values

Job event `data` fields

Verifying deliveries

Job types

Job states

Subscription status values

API endpoints

Webhooks

Subscribing to Notifications

Job Types

Webhooks API

​Subscription response fields

​Create request fields

​Job subscription

​App subscription

​Delivery payload

​type values

​Job event data fields

​Verifying deliveries

​Job types

​Job states

​Subscription status values

​API endpoints

​Related content

Webhooks

Subscribing to Notifications

Job Types

Webhooks API

Subscription response fields

Create request fields

Job subscription

App subscription

Delivery payload

`type` values

Job event `data` fields

Verifying deliveries

Job types

Job states

Subscription status values

API endpoints

Related content