Types & Formats | Airweave

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

Event Types

sync.pending

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

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

sync.running

Fired when the sync job starts processing.

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

sync.completed

Fired when the sync job finishes successfully.

1 {
2   "event_type": "sync.completed",
3   "job_id": "550e8400-e29b-41d4-a716-446655440000",
4   "collection_readable_id": "finance-data-ab123",
5   "collection_name": "Finance Data",
6   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
7   "source_type": "notion",
8   "status": "completed",
9   "timestamp": "2025-01-15T14:05:00Z"
10 }

sync.failed

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

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

sync.cancelled

Fired when the sync job is manually cancelled.

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

Payload Schema

Every event payload follows this structure:

Field	Type	Description
`event_type`	string	The event type (e.g., `sync.completed`)
`job_id`	UUID	Unique identifier for the sync job
`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`)
`status`	string	Current job status: `pending`, `running`, `completed`, `failed`, `cancelled`
`timestamp`	ISO 8601	When the event occurred
`error`	string	Error message (only present for `sync.failed` events)

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.