Knowledge Base

Creating Webhook Subscriptions

Create webhook subscriptions to receive real-time notifications about job state changes and other events in the Narrative platform.

Endpoint

POST https://api.narrative.io/webhooks

Authentication

All requests require Bearer token authentication:

Authorization: Bearer YOUR_API_TOKEN

Request Body

Job State Webhook Subscription Example

{
    "type": "webhook_subscription_jobs",
    "job_types": [
        "materialize-view"
    ],
    "url": "https://your-webhook-endpoint.com/webhooks/narrative",
    "states": [
        "pending",
        "running",
        "completed"
    ]
}

App Event Webhook Subscription Example

{
    "type": "webhook_subscription_app",
    "app_id": "11",
    "url": "https://your-webhook-endpoint.com/webhooks/app-events",
    "name": "thetradedesk_connector_monitoring"
}

Request Parameters

Job Subscription Parameters

Field	Type	Required	Description
`type`	string	Yes	Use `"webhook_subscription_jobs"` for job event notifications
`job_types`	array	Yes	Array of job types to monitor (see supported job types below)
`url`	string	Yes	The HTTPS endpoint where webhook payloads will be sent
`states`	array	Yes	Array of job states to monitor (see supported job states below)
`job_ids`	array	No	Optional array of specific job UUIDs to monitor
`name`	string	No	Optional name for the webhook subscription

App Subscription Parameters

Field	Type	Required	Description
`type`	string	Yes	Use `"webhook_subscription_app"` for app event notifications
`app_id`	string	Yes	ID of the Narrative app to monitor (see app events reference)
`url`	string	Yes	The HTTPS endpoint where webhook payloads will be sent
`name`	string	No	Optional name for the webhook subscription

Supported Job Types

The Narrative platform supports monitoring many different job types through webhooks, from data processing to model training.

Supported Job States

pending: Job has been queued but not yet started
running: Job is currently executing
completed: Job has finished successfully
pending_cancellation: Job is being cancelled
cancelled: Job was cancelled before completion
failed: Job encountered an error and could not complete

Example Requests

Basic Job Monitoring

Monitor materialized view jobs for most states:

curl --location 'https://api.narrative.io/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "type": "webhook_subscription_jobs",
    "job_types": [
        "materialize-view"
    ],
    "url": "https://your-webhook-endpoint.com/webhooks",
    "states": [
        "pending",
        "running",
        "completed",
        "failed"
    ]
}'

Monitor Multiple Job Types

Subscribe to both materialize-view and forecast jobs:

curl --location 'https://api.narrative.io/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "type": "webhook_subscription_jobs",
    "job_types": [
        "materialize-view",
        "forecast"
    ],
    "url": "https://your-webhook-endpoint.com/webhooks",
    "states": [
        "completed",
        "failed"
    ]
}'

Monitor App Events

Subscribe to all events from a specific Narrative app:

curl --location 'https://api.narrative.io/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
    "type": "webhook_subscription_app",
    "app_id": "8",
    "url": "https://your-webhook-endpoint.com/app-events",
    "name": "facebook_connector_monitoring"
}'

Success Response

Status Code: 201 Created

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "webhook_subscription_jobs", 
    "company_id": 123,
    "job_types": [
        "materialize-view"
    ],
    "states": [
        "pending",
        "running",
        "completed"
    ],
    "url": "https://your-webhook-endpoint.com/webhooks/narrative",
    "created_at": "2025-01-21T16:12:45.123456Z",
    "updated_at": "2025-01-21T16:12:45.123456Z"
}

Next Steps

Managing Subscriptions

Now that you've created webhook subscriptions, learn how to monitor and manage them effectively.

Manage subscriptions