A webhook subscription is a registration that tells Narrative to send an HTTP POST request to your URL whenever a job changes state. Instead of polling the jobs API to check whether something finished, you receive a notification the moment it happens.
Why webhooks exist
Many Narrative operations are asynchronous. When you create a materialized view, refresh a dataset, or run an inference job, the platform returns a job ID and processes the work in the background. To know when the job finishes, you have two options:
Polling means repeatedly calling the jobs API to check the current state. This works, but it’s wasteful—most requests return the same “still running” response—and introduces latency between when the job completes and when your system finds out.
Webhooks invert the flow. You register a URL once, and Narrative pushes an event to you the moment a job transitions to a state you care about. No wasted API calls, no delay.
Webhooks are especially valuable when you need to:
- Trigger downstream workflows — start a data pipeline step as soon as the previous job completes
- Alert on failures — notify your team immediately when a job fails, rather than discovering it during the next manual check
- Integrate with external systems — forward job status to Slack, PagerDuty, or your own orchestration layer
How job webhooks work
When you create a webhook subscription, you specify:
- A URL — the HTTPS endpoint that receives event payloads
- Filters (optional) — which jobs you care about, by job ID, job type, or job state
When a job transitions to a matching state, Narrative sends an HTTP POST request to your URL with a JSON payload describing the event.
Filtering
Filters let you control which events trigger a notification. You can combine them to match exactly the events you need:
| Filter | Effect |
|---|
job_ids | Only notify for specific job IDs |
job_types | Only notify for specific job types (e.g., materialize-view, forecast) |
states | Only notify for specific state transitions (e.g., completed, failed) |
How delivery works
- A job transitions to a new state (e.g.,
running to completed)
- The webhook service checks all active subscriptions for that company
- For each matching subscription, it sends an HTTP POST to the registered URL
- Your endpoint should respond with a
2xx status code to acknowledge receipt
Each event includes an idempotency key so your endpoint can detect and discard duplicate deliveries.
Webhook lifecycle
Subscriptions have two statuses:
| Status | Description |
|---|
active | The subscription is live and will receive events |
archived | The subscription is disabled and no longer receives events |
DELETE request. Archived subscriptions are retained for audit purposes but stop generating events.
Security
Each subscription is assigned a shared secret (a UUID) when it’s created. This secret is returned in the creation response and should be stored securely. Use it to verify that incoming webhook requests genuinely originated from Narrative rather than a third party.
All webhook endpoints must use HTTPS to ensure payloads are encrypted in transit.
Narrative also supports app webhooks for application-level events. App webhooks use a different subscription type (webhook_subscription_app) and are scoped to a specific application rather than job state changes. This documentation focuses on job webhooks, which are the most common use case.
Related content
