Sign in

v50

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-222763184.3 KB
webhooks

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.

post/webhooks/subscriptions

Request body

urlstring uri required

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

event_typesEventType[] required

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 nullable

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.

Example request

{
  "event_types": [
    "sync.completed",
    "sync.failed"
  ],
  "url": "https://api.mycompany.com/webhooks/airweave"
}

Response

Created subscription

idstring required

Unique identifier for this subscription (UUID format)

urlstring required

The URL where webhook events are delivered

filter_typesstring[] nullable

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

disabledboolean

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

descriptionstring nullable

Optional human-readable description of this subscription

created_atstring date-time required

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

updated_atstring date-time required

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

health_status'healthy' | 'degraded' | 'failing' | 'unknown'

Health status of a webhook subscription based on recent delivery attempts.

Example response

{
  "created_at": "2024-03-01T08:00:00Z",
  "description": "Production notifications for data team",
  "disabled": false,
  "filter_types": [
    "sync.completed",
    "sync.failed"
  ],
  "health_status": "healthy",
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "updated_at": "2024-03-15T14:30:00Z",
  "url": "https://api.mycompany.com/webhooks/airweave"
}