Managing Webhook Subscriptions

Once you've created webhook subscriptions, you can list, view details, and archive them using the management endpoints.

List All Webhook Subscriptions

Retrieve all webhook subscriptions for your company.

Endpoint

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

Example Request

curl --location 'https://api.narrative.io/webhooks' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Success Response

Status Code: 200 OK

[
  {
    "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"
  },
  {
    "id": "456e7890-e12b-34c5-d678-901234567890",
    "type": "webhook_subscription_app",
    "company_id": 123,
    "app_id": "8",
    "url": "https://api.example.com/webhooks/narrative",
    "name": "facebook_connector_monitoring",
    "created_at": "2025-01-21T16:15:22.789012Z",
    "updated_at": "2025-01-21T16:15:22.789012Z"
  },
  {
    "id": "789abc12-def3-4567-890a-bcdef1234567",
    "type": "webhook_subscription_app",
    "company_id": 123,
    "app_id": "11",
    "url": "https://your-webhook-endpoint.com/app-events",
    "name": "thetradedesk_connector_monitoring",
    "created_at": "2025-01-21T16:18:33.456789Z",
    "updated_at": "2025-01-21T16:18:33.456789Z"
  }
]

Get Webhook Subscription Details

Retrieve detailed information about a specific webhook subscription.

Endpoint

GET https://api.narrative.io/webhooks/{webhook_subscription_id}

Path Parameters

Example Request

curl --location 'https://api.narrative.io/webhooks/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Success Response

Status Code: 200 OK

{
  "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",
  "events_sent": 247,
  "last_event_sent_at": "2025-01-21T18:45:12.123456Z",
  "delivery_stats": {
    "successful_deliveries": 245,
    "failed_deliveries": 2,
    "last_successful_delivery_at": "2025-01-21T18:45:12.123456Z",
    "last_failed_delivery_at": "2025-01-21T17:23:45.678901Z"
  }
}

Archive Webhook Subscription

Archive (delete) a webhook subscription. This permanently stops webhook deliveries for this subscription.

Endpoint

DELETE https://api.narrative.io/webhooks/{webhook_subscription_id}

Path Parameters

Example Request

curl --location --request DELETE 'https://api.narrative.io/webhooks/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Success Response

Status Code: 204 No Content

The webhook subscription has been successfully archived and will no longer receive events.

Error Responses

Webhook Not Found

Status Code: 404 Not Found

The specified webhook subscription ID does not exist or does not belong to your company.

Unauthorized

Status Code: 401 Unauthorized

Check your Bearer token and ensure it has webhook permissions.

Related Resources