> ## 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.

# Webhooks

> How webhooks deliver push-based notifications for job state changes

A webhook subscription is a registration that tells Narrative to send an HTTP POST request to your URL whenever a [job](/reference/architecture/job-types) 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:

1. **A URL** — the HTTPS endpoint that receives event payloads
2. **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`)  |

If you omit all filters, the subscription fires for every job state change in your company.

## How delivery works

```mermaid theme={null}
sequenceDiagram
    participant J as Job System
    participant W as Webhook Service
    participant Y as Your Endpoint

    J->>W: Job state changed
    W->>W: Match against subscriptions
    W->>Y: HTTP POST with event payload
    Y->>W: 200 OK
```

1. A job transitions to a new state (e.g., `running` to `completed`)
2. The webhook service checks all active subscriptions for that company
3. For each matching subscription, it sends an HTTP POST to the registered URL
4. Your endpoint should respond with a `2xx` status code to acknowledge receipt

Each event includes an [idempotency key](/reference/glossary#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 |

When you no longer need a subscription, archive it with a `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.

<Note>
  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.
</Note>

***

## Related content

<CardGroup cols={2}>
  <Card title="Subscribing to Notifications" icon="bell" href="/guides/webhooks/subscribing-to-notifications">
    Step-by-step guide to creating and managing webhook subscriptions
  </Card>

  <Card title="Webhook Event Reference" icon="list-check" href="/reference/webhooks/event-reference">
    Complete field reference for webhook requests and responses
  </Card>

  <Card title="Tracking Job Status" icon="spinner" href="/guides/sdk/tracking-jobs">
    Poll-based alternative for monitoring job progress
  </Card>

  <Card title="Job Types" icon="list" href="/reference/architecture/job-types">
    All job types that can trigger webhook events
  </Card>
</CardGroup>