Webhook Event Reference

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

Example response:

{
  "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)

Example request:

{
  "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
`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.

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

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 all job types

Webhooks API

Full REST API documentation for webhook endpoints

Overview

Connectors

Integrations

Workflow Reference

Webhook Reference

Security Reference

Architecture Reference

Error Reference

Model Inference Reference

Rosetta Stone Reference

UI Reference

SDKs

Glossary

Billing

Subscription response fields

Job webhook request fields

Job types

Job states

Subscription status values

API endpoints

Webhooks

Subscribing to Notifications

Job Types

Webhooks API

​Subscription response fields

​Job webhook request fields

​Job types

​Job states

​Subscription status values

​API endpoints

​Related content

Webhooks

Subscribing to Notifications

Job Types

Webhooks API

Subscription response fields

Job webhook request fields

Job types

Job states

Subscription status values

API endpoints

Related content