Skip to main content
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.
FieldTypeRequiredDescription
idstring (UUID)YesUnique identifier for the subscription
secretstring (UUID)YesShared secret for verifying webhook deliveries. Only returned on creation
statusstringYesSubscription status: active or archived
companyIdintegerYesID of the company that owns the subscription
jobIdsarray of strings (UUID)NoJob IDs this subscription is filtered to
jobStatesarray of stringsNoJob states this subscription is filtered to
jobTypesarray of stringsNoJob types this subscription is filtered to
urlstring (URI)YesHTTPS endpoint that receives event payloads
createdAtstring (date-time)YesWhen the subscription was created
updatedAtstring (date-time)YesWhen 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.
FieldTypeRequiredDescription
typestringYesMust be webhook_subscription_jobs
urlstring (URI)YesHTTPS endpoint to receive events
namestringNoHuman-readable name for the subscription
job_idsarray of strings (UUID)NoSpecific job IDs to monitor
job_typesarray of stringsNoJob types to monitor (see Job types)
statesarray of stringsNoJob 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.
ValueDescription
costsCost calculation job
datasets_calculate_column_statsColumn statistics computation
datasets_delete_tableDataset table deletion
datasets_deliver_dataData delivery to external destinations
datasets_sampleDataset sampling
datasets_suggest_mappingsAI-powered mapping suggestions
delete-snowflake-tableSnowflake table deletion
forecastQuery cost forecasting
materialize-viewMaterialized view creation or refresh
models_deliver_modelModel delivery
model_training_runModel training execution
nql-forecastNQL query forecasting
upload-statsUpload statistics computation

​
Job states

The states filter accepts these values. Jobs progress through these states during their lifecycle.
ValueDescription
pendingJob is queued and waiting for execution
runningJob is currently being executed
completedJob finished successfully
pending_cancellationJob is marked for cancellation but still running
cancelledJob was cancelled before completion
failedJob execution failed
For more details on job state transitions, see Tracking Job Status.

​
Subscription status values

ValueDescription
activeSubscription is live and receiving events
archivedSubscription is disabled and no longer receives events

​
API endpoints

MethodPathDescription
GET/webhooksList all webhook subscriptions
POST/webhooksCreate a webhook subscription
GET/webhooks/{webhook_subscription_id}Get a subscription by ID
DELETE/webhooks/{webhook_subscription_id}Archive a subscription

​
Related content

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