Types & Formats | Airweave

This page documents the structure of webhook payloads, delivery headers, and the data models used throughout the Webhooks API.

Event Types

Events are organized by domain. Each domain has its own payload structure.

Sync Events

sync.pending

Fired when a sync job is created and queued for processing.

1 {
2   "event_type": "sync.pending",
3   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
4   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
5   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
6   "collection_readable_id": "finance-data-ab123",
7   "collection_name": "Finance Data",
8   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
9   "source_type": "notion",
10   "timestamp": "2025-01-15T14:00:00Z"
11 }

sync.running

Fired when the sync job starts processing.

1 {
2   "event_type": "sync.running",
3   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
4   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
5   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
6   "collection_readable_id": "finance-data-ab123",
7   "collection_name": "Finance Data",
8   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
9   "source_type": "notion",
10   "timestamp": "2025-01-15T14:00:05Z"
11 }

sync.completed

Fired when the sync job finishes successfully. Includes entity and chunk metrics.

1 {
2   "event_type": "sync.completed",
3   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
4   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
5   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
6   "collection_readable_id": "finance-data-ab123",
7   "collection_name": "Finance Data",
8   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
9   "source_type": "notion",
10   "entities_inserted": 42,
11   "entities_updated": 10,
12   "entities_deleted": 3,
13   "entities_skipped": 120,
14   "chunks_written": 215,
15   "timestamp": "2025-01-15T14:05:00Z"
16 }

sync.failed

Fired when the sync job encounters an error. Includes an error field with details.

1 {
2   "event_type": "sync.failed",
3   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
4   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
5   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
6   "collection_readable_id": "finance-data-ab123",
7   "collection_name": "Finance Data",
8   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
9   "source_type": "notion",
10   "error": "Authentication token expired",
11   "timestamp": "2025-01-15T14:02:30Z"
12 }

sync.cancelled

Fired when the sync job is manually cancelled.

1 {
2   "event_type": "sync.cancelled",
3   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
4   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
5   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
6   "collection_readable_id": "finance-data-ab123",
7   "collection_name": "Finance Data",
8   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
9   "source_type": "notion",
10   "timestamp": "2025-01-15T14:01:15Z"
11 }

Sync Payload Schema

Field	Type	Description
`event_type`	string	The event type (e.g., `sync.completed`)
`sync_id`	UUID	Unique identifier for the sync definition
`sync_job_id`	UUID	Unique identifier for this sync job run
`collection_id`	UUID	Unique identifier for the collection
`collection_readable_id`	string	Human-readable collection ID (e.g., `sales-data-ab123`)
`collection_name`	string	Display name of the collection
`source_connection_id`	UUID	Unique identifier for the source connection
`source_type`	string	Short name of the source (e.g., `slack`, `notion`, `github`)
`entities_inserted`	integer	Number of new entities inserted (only for `sync.completed`)
`entities_updated`	integer	Number of entities updated (only for `sync.completed`)
`entities_deleted`	integer	Number of entities deleted (only for `sync.completed`)
`entities_skipped`	integer	Number of unchanged entities skipped (only for `sync.completed`)
`chunks_written`	integer	Number of chunks written to destination (only for `sync.completed`)
`error`	string	Error message (only for `sync.failed`)
`timestamp`	ISO 8601	When the event occurred

Source Connection Events

source_connection.created

Fired when a new source connection record is created. The connection may or may not be authenticated yet (e.g., OAuth flow not completed).

1 {
2   "event_type": "source_connection.created",
3   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
4   "collection_readable_id": "finance-data-ab123",
5   "source_type": "notion",
6   "is_authenticated": false,
7   "timestamp": "2025-01-15T13:55:00Z"
8 }

source_connection.auth_completed

Fired when the OAuth flow completes and the connection is now authenticated and ready to use.

1 {
2   "event_type": "source_connection.auth_completed",
3   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
4   "collection_readable_id": "finance-data-ab123",
5   "source_type": "notion",
6   "is_authenticated": true,
7   "timestamp": "2025-01-15T13:56:00Z"
8 }

source_connection.deleted

Fired when a source connection and its associated data are removed.

1 {
2   "event_type": "source_connection.deleted",
3   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
4   "collection_readable_id": "finance-data-ab123",
5   "source_type": "notion",
6   "is_authenticated": false,
7   "timestamp": "2025-01-15T16:00:00Z"
8 }

Source Connection Payload Schema

Field	Type	Description
`event_type`	string	The event type (e.g., `source_connection.created`)
`source_connection_id`	UUID	Unique identifier for the source connection
`collection_readable_id`	string	Human-readable ID of the collection this connection belongs to
`source_type`	string	Short name of the source (e.g., `slack`, `notion`, `github`)
`is_authenticated`	boolean	Whether the connection is currently authenticated
`timestamp`	ISO 8601	When the event occurred

Collection Events

collection.created

Fired when a new collection is created.

1 {
2   "event_type": "collection.created",
3   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
4   "collection_name": "Finance Data",
5   "collection_readable_id": "finance-data-ab123",
6   "timestamp": "2025-01-15T13:50:00Z"
7 }

collection.updated

Fired when collection properties are changed (name, configuration, etc.).

1 {
2   "event_type": "collection.updated",
3   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
4   "collection_name": "Finance Data (Updated)",
5   "collection_readable_id": "finance-data-ab123",
6   "timestamp": "2025-01-15T15:00:00Z"
7 }

collection.deleted

Fired when a collection and all associated data are removed.

1 {
2   "event_type": "collection.deleted",
3   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
4   "collection_name": "Finance Data",
5   "collection_readable_id": "finance-data-ab123",
6   "timestamp": "2025-01-15T17:00:00Z"
7 }

Collection Payload Schema

Field	Type	Description
`event_type`	string	The event type (e.g., `collection.created`)
`collection_id`	UUID	Unique identifier for the collection
`collection_name`	string	Display name of the collection
`collection_readable_id`	string	Human-readable collection ID (e.g., `sales-data-ab123`)
`timestamp`	ISO 8601	When the event occurred

Delivery Format

When Airweave delivers an event to your webhook endpoint, the HTTP request includes:

Headers

Header	Description	Example
`Content-Type`	Always `application/json`	`application/json`
`svix-id`	Unique message identifier	`msg_2xKvB8LPqM4nRst`
`svix-timestamp`	Unix timestamp of delivery	`1705329000`
`svix-signature`	HMAC-SHA256 signature for verification	`v1,g0hM9SsE+OTPJTGt/...`

Body

The request body is the raw event payload (JSON).

Expected Response

Your endpoint should return a 2xx status code to acknowledge receipt:

Response	Meaning
`200-299`	Success. Message delivered
`4xx`	Client error, will retry
`5xx`	Server error, will retry
Timeout (30s)	Delivery failed, will retry

Webhook Subscription

When you create or retrieve a subscription, you’ll see this structure:

1 {
2   "id": "ep_2bVxUn3RFnLYHa8z6ZKHMT9PqPX",
3   "url": "https://your-server.com/webhooks/airweave",
4   "filter_types": ["sync.completed", "sync.failed"],
5   "disabled": false,
6   "description": "Production webhook endpoint",
7   "created_at": "2025-01-15T10:30:00Z",
8   "updated_at": "2025-01-15T10:30:00Z"
9 }

Field	Type	Description
`id`	string	Unique subscription ID (prefix: `ep_`)
`url`	string	Your webhook endpoint URL
`filter_types`	array	Event types this subscription receives
`disabled`	boolean	Whether delivery is paused
`description`	string	Optional description
`created_at`	ISO 8601	When the subscription was created
`updated_at`	ISO 8601	When the subscription was last modified

Webhook Message

When retrieving messages via the API, each message has this structure:

1 {
2   "id": "msg_2bVxUn3RFnLYHa8z6ZKHMT9PqPX",
3   "event_type": "sync.completed",
4   "payload": {
5     "event_type": "sync.completed",
6     "job_id": "550e8400-e29b-41d4-a716-446655440000",
7     "collection_readable_id": "finance-data-ab123",
8     "collection_name": "Finance Data",
9     "source_connection_id": "880e8400-e29b-41d4-a716-446655440003",
10     "source_type": "slack",
11     "status": "completed",
12     "timestamp": "2025-01-15T14:22:15Z"
13   },
14   "timestamp": "2025-01-15T14:22:15Z",
15   "channels": ["sync.completed"],
16   "event_id": "evt_550e8400e29b41d4a716446655440000",
17   "tags": ["sync", "slack"]
18 }

Field	Type	Description
`id`	string	Unique message ID (prefix: `msg_`)
`event_type`	string	The event type
`payload`	object	The full event payload
`timestamp`	ISO 8601	When the message was created
`channels`	array	Delivery channels (typically matches event type)
`event_id`	string	Deduplication ID for idempotency
`tags`	array	Tags for filtering

Delivery Attempt

When you retrieve delivery attempts (via include_attempts=true or the subscription endpoint), each attempt has this structure:

1 {
2   "id": "atmpt_2bVxUn3RFnLYHa8z6ZKHMT9PqPX",
3   "message_id": "msg_2bVxUn3RFnLYHa8z6ZKHMT9PqPX",
4   "endpoint_id": "ep_2bVxUn3RFnLYHa8z6ZKHMT9PqPX",
5   "response": "{\"received\": true}",
6   "response_status_code": 200,
7   "status": "success",
8   "timestamp": "2025-01-15T14:22:15Z"
9 }

Field	Type	Description
`id`	string	Unique attempt ID (prefix: `atmpt_`)
`message_id`	string	The message being delivered
`endpoint_id`	string	The subscription endpoint
`response`	string	Response body from your endpoint
`response_status_code`	integer	HTTP status code returned
`status`	string	`success`, `pending`, or `failed`
`timestamp`	ISO 8601	When the attempt occurred

Retry Schedule

Failed deliveries are retried with exponential backoff:

Attempt	Delay After Failure
1	Immediate
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the message is marked as failed. You can manually recover failed messages using the recover endpoint.

Next Steps

Setup Guide

Learn how to create subscriptions, verify signatures, and handle events in your application.