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.
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.
disabledbooleanDefaults 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
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).
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.
