Skip to navigation
API ReferenceWebhooks

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.

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 nullOptional
Event types this subscription is filtered to receive. See EventType enum for all available types.
disabledbooleanOptionalDefaults to false
Whether this subscription is currently disabled. Disabled subscriptions do not receive event deliveries.
descriptionstring or nullOptional

Optional human-readable description of this subscription

health_statusenumOptional

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:

Errors

422
Unprocessable Entity Error
429
Too Many Requests Error