Create Subscription

Create a new webhook subscription.

Webhook subscriptions allow you to receive real-time notifications when events occur in Airweave. When you create a subscription, you specify:

URL: The HTTPS endpoint where events will be delivered
Event Types: Which events you want to receive (e.g., sync.completed, sync.failed)
Secret (optional): A custom signing secret for verifying webhook signatures

After creation, Airweave will send HTTP POST requests to your URL whenever matching events occur. Each request includes a signature header for verification.

Create a new webhook subscription. Webhook subscriptions allow you to receive real-time notifications when events occur in Airweave. When you create a subscription, you specify: - **URL**: The HTTPS endpoint where events will be delivered - **Event Types**: Which events you want to receive (e.g., `sync.completed`, `sync.failed`) - **Secret** (optional): A custom signing secret for verifying webhook signatures After creation, Airweave will send HTTP POST requests to your URL whenever matching events occur. Each request includes a signature header for verification.

Authentication

x-api-keystring

API Key authentication via header

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"1-2083 characters

The HTTPS URL where webhook events will be delivered. Must be a publicly accessible endpoint that returns a 2xx status code.

event_typeslist of enumsRequired

List of event types to subscribe to. Events not in this list will not be delivered to this subscription. Available types: sync.pending, sync.running, sync.completed, sync.failed, sync.cancelled, source_connection.created, source_connection.auth_completed, source_connection.deleted, collection.created, collection.updated, collection.deleted.

List of event types to subscribe to. Events not in this list will not be delivered to this subscription. Available types: `sync.pending`, `sync.running`, `sync.completed`, `sync.failed`, `sync.cancelled`, `source_connection.created`, `source_connection.auth_completed`, `source_connection.deleted`, `collection.created`, `collection.updated`, `collection.deleted`.

secretstring or nullOptional>=24 characters

Optional custom signing secret for webhook signature verification. If not provided, a secure secret will be auto-generated. Must be at least 24 characters if specified.

Response

Created subscription

idstring

Unique identifier for this subscription (UUID format)

urlstring

The URL where webhook events are delivered

created_atstringformat: "date-time"

When this subscription was created (ISO 8601 format, UTC)

updated_atstringformat: "date-time"

When this subscription was last updated (ISO 8601 format, UTC)

filter_typeslist of strings or null

Event types this subscription is filtered to receive. See EventType enum for all available types.

disabledboolean or nullDefaults to false

Whether this subscription is currently disabled. Disabled subscriptions do not receive event deliveries.

descriptionstring or null

Optional human-readable description of this subscription

health_statusenum or null

Health status of this subscription based on recent delivery attempts. Values: ‘healthy’ (all recent deliveries succeeded), ‘degraded’ (mix of successes and failures), ‘failing’ (consecutive failures beyond threshold), ‘unknown’ (no delivery data yet).

Allowed values:

1	from airweave import AirweaveSDK
2
3	client = AirweaveSDK(
4	api_key="YOUR_API_KEY",
5	)
6	client.webhooks.create_subscription(
7	url="https://api.mycompany.com/webhooks/airweave",
8	event_types=["sync.completed", "sync.failed"],
9	)

1	{
2	"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
3	"url": "https://api.mycompany.com/webhooks/airweave",
4	"created_at": "2024-03-01T08:00:00Z",
5	"updated_at": "2024-03-15T14:30:00Z",
6	"filter_types": [
7	"sync.completed",
8	"sync.failed"
9	],
10	"disabled": false,
11	"description": "Production notifications for data team",
12	"health_status": "healthy"
13	}

Authentication

Request

Response

Errors