> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Event Reference
> Complete field reference for webhook subscriptions, event payloads, and supported enum values
This reference documents all fields, types, and enum values for the webhook subscription system. For a conceptual overview, see [Webhooks](/concepts/webhooks/overview). For step-by-step usage, see [Subscribing to Notifications](/guides/webhooks/subscribing-to-notifications).
## Subscription response fields
When you create or retrieve a webhook subscription, the response contains these fields.
| Field | Type | Required | Description |
| ----------- | ----------------------- | -------- | ------------------------------------------------------------------------- |
| `id` | string (UUID) | Yes | Unique identifier for the subscription |
| `secret` | string (UUID) | Yes | Shared secret for verifying webhook deliveries. Only returned on creation |
| `status` | string | Yes | Subscription status: `active` or `archived` |
| `companyId` | integer | Yes | ID of the company that owns the subscription |
| `jobIds` | array of strings (UUID) | No | Job IDs this subscription is filtered to |
| `jobStates` | array of strings | No | Job states this subscription is filtered to |
| `jobTypes` | array of strings | No | Job types this subscription is filtered to |
| `url` | string (URI) | Yes | HTTPS endpoint that receives event payloads |
| `createdAt` | string (date-time) | Yes | When the subscription was created |
| `updatedAt` | string (date-time) | Yes | When the subscription was last updated |
**Example response:**
```json theme={null}
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"secret": "8b6dba8c-9a8b-4a3a-8469-9dc7a33c3e17",
"status": "active",
"companyId": 42,
"jobIds": ["d35a12c1-7a2f-46b9-8d60-9e0a2a84c205"],
"jobStates": ["completed", "failed"],
"jobTypes": ["materialize-view"],
"url": "https://your-app.example.com/webhooks/narrative",
"createdAt": "2025-04-29T16:12:45.123456",
"updatedAt": "2025-04-29T16:12:45.123456"
}
```
***
## Job webhook request fields
To create a job webhook subscription, send a `POST /webhooks` request with these fields.
| Field | Type | Required | Description |
| ----------- | ----------------------- | -------- | ----------------------------------------------------- |
| `type` | string | Yes | Must be `webhook_subscription_jobs` |
| `url` | string (URI) | Yes | HTTPS endpoint to receive events |
| `name` | string | No | Human-readable name for the subscription |
| `job_ids` | array of strings (UUID) | No | Specific job IDs to monitor |
| `job_types` | array of strings | No | Job types to monitor (see [Job types](#job-types)) |
| `states` | array of strings | No | Job states to monitor (see [Job states](#job-states)) |
**Example request:**
```json theme={null}
{
"type": "webhook_subscription_jobs",
"url": "https://your-app.example.com/webhooks/narrative",
"name": "failed_job_alerts",
"job_types": ["materialize-view", "forecast"],
"states": ["failed"]
}
```
If you omit all filter fields (`job_ids`, `job_types`, `states`), the subscription fires for every job state change in your company.
***
## Job types
The `job_types` filter accepts these values. For detailed descriptions of each type, see [Job Types](/reference/architecture/job-types).
| Value | Description |
| --------------------------------- | -------------------------------------- |
| `costs` | Cost calculation job |
| `datasets_calculate_column_stats` | Column statistics computation |
| `datasets_delete_table` | Dataset table deletion |
| `datasets_deliver_data` | Data delivery to external destinations |
| `datasets_sample` | Dataset sampling |
| `datasets_suggest_mappings` | AI-powered mapping suggestions |
| `delete-snowflake-table` | Snowflake table deletion |
| `forecast` | Query cost forecasting |
| `materialize-view` | Materialized view creation or refresh |
| `models_deliver_model` | Model delivery |
| `model_training_run` | Model training execution |
| `nql-forecast` | NQL query forecasting |
| `upload-stats` | Upload statistics computation |
***
## Job states
The `states` filter accepts these values. Jobs progress through these states during their lifecycle.
| 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 more details on job state transitions, see [Tracking Job Status](/guides/sdk/tracking-jobs).
***
## Subscription status values
| Value | Description |
| ---------- | ------------------------------------------------------ |
| `active` | Subscription is live and receiving events |
| `archived` | Subscription is disabled and no longer receives events |
***
## API endpoints
| Method | Path | Description |
| -------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET` | `/webhooks` | [List all webhook subscriptions](/api-reference/webhooks/list-webhook-subscriptions) |
| `POST` | `/webhooks` | [Create a webhook subscription](/api-reference/webhooks/create-a-webhook-subscription) |
| `GET` | `/webhooks/{webhook_subscription_id}` | [Get a subscription by ID](/api-reference/webhooks/get-a-webhook-subscription-by-id) |
| `DELETE` | `/webhooks/{webhook_subscription_id}` | [Archive a subscription](/api-reference/webhooks/archive-a-webhook-subscription) |
***
## Related content
How webhooks work and when to use them
Step-by-step guide to creating and managing subscriptions
Detailed descriptions of all job types
Full REST API documentation for webhook endpoints