This reference documents all fields, types, and enum values for the webhook subscription system. For a conceptual overview, see Webhooks. For step-by-step usage, see 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 |
{
"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) |
states | array of strings | No | Job states to monitor (see Job states) |
{
"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.
| 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 |
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 |
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 |
POST | /webhooks | Create a webhook subscription |
GET | /webhooks/{webhook_subscription_id} | Get a subscription by ID |
DELETE | /webhooks/{webhook_subscription_id} | Archive a subscription |
Related content
