Skip to main content

​
Overview

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.

​
List Subscriptions

​
/v1/webhooks/subscriptions
List all webhook subscriptions for your organization

​
Response

Returns an array of subscription objects.
​
id
string
required
Unique UUID identifier for this subscription
​
url
string
required
The URL where webhook events are delivered
​
filter_types
array
Event types this subscription receives
​
disabled
boolean
required
Whether this subscription is currently disabled
​
health_status
string
required
Health status: healthy, degraded, failing, or unknown
​
created_at
string
required
ISO 8601 timestamp when created
​
updated_at
string
required
ISO 8601 timestamp when last updated

​
Example Request

cURL
curl https://api.airweave.ai/v1/webhooks/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get Subscription

​
/v1/webhooks/subscriptions/{subscription_id}
Retrieve a specific webhook subscription with its recent delivery attempts

​
Path Parameters

​
subscription_id
string
required
UUID of the subscription to retrieve

​
Query Parameters

​
include_secret
boolean
default:false
Include the signing secret for webhook signature verification

​
Response

Returns a subscription object with delivery attempts.
​
delivery_attempts
array
Recent delivery attempts for this subscription
​
secret
string
Signing secret (only included when include_secret=true)

​
Example Request

cURL
curl "https://api.airweave.ai/v1/webhooks/subscriptions/550e8400-e29b-41d4-a716-446655440000?include_secret=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create Subscription

​
/v1/webhooks/subscriptions
Create a new webhook subscription

​
Request Body

​
url
string
required
The HTTPS URL where webhook events will be deliveredMust be a publicly accessible endpoint that returns a 2xx status code.
​
event_types
array
required
List of event types to subscribe toAvailable 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
​
secret
string
Optional custom signing secret for webhook signature verification (min 24 characters)If not provided, a secure secret will be auto-generated.

​
Example Request

curl -X POST https://api.airweave.ai/v1/webhooks/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.mycompany.com/webhooks/airweave",
    "event_types": ["sync.completed", "sync.failed"]
  }'

​
Update Subscription

​
/v1/webhooks/subscriptions/{subscription_id}
Update an existing webhook subscription

​
Request Body

All fields are optional. Only include fields you want to change.
​
url
string
New URL for webhook delivery
​
event_types
array
New list of event types (replaces existing list)
​
disabled
boolean
Set to true to pause delivery, false to resume
​
recover_since
string
When re-enabling (disabled: false), optionally recover failed messages from this timestamp (ISO 8601)

​
Example Request

Disable Subscription
curl -X PATCH https://api.airweave.ai/v1/webhooks/subscriptions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'

​
Delete Subscription

​
/v1/webhooks/subscriptions/{subscription_id}
Permanently delete a webhook subscription
Once deleted, Airweave will stop sending events to this endpoint immediately. This action cannot be undone.

​
Path Parameters

​
subscription_id
string
required
UUID of the subscription to delete

​
Example Request

cURL
curl -X DELETE https://api.airweave.ai/v1/webhooks/subscriptions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Recover Failed Messages

​
/v1/webhooks/subscriptions/{subscription_id}/recover
Retry failed message deliveries for a webhook subscription

​
Request Body

​
since
string
required
Start of the recovery time window (ISO 8601)All failed messages from this time onward will be retried.
​
until
string
End of the recovery time window (ISO 8601)If not specified, recovers all failed messages up to now.

​
Response

​
id
string
required
Unique identifier for this recovery task
​
status
string
required
Recovery task status: running or completed

​
Example Request

cURL
curl -X POST https://api.airweave.ai/v1/webhooks/subscriptions/550e8400-e29b-41d4-a716-446655440000/recover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2024-03-14T00:00:00Z",
    "until": "2024-03-15T00:00:00Z"
  }'