> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.

# Webhooks Overview

> Real-time notifications for sync, source connection, and collection lifecycle events via webhooks

**Beta Feature**

The Webhooks API is currently in beta. The API is stable but may receive enhancements based on feedback.

## What are Webhooks?

Webhooks are real-time notifications that Airweave sends when things happen in your organization: syncs completing, source connections being created, collections being updated. Instead of constantly polling the API, you register a webhook endpoint and Airweave pushes updates to you the moment they occur.

This is the foundation for building reactive integrations. Trigger downstream workflows, update dashboards, send alerts, or sync state with external systems automatically.

## Why Use Webhooks?

| Polling                               | Webhooks                          |
| ------------------------------------- | --------------------------------- |
| You repeatedly ask "is it done yet?"  | Airweave tells you when it's done |
| Wastes API calls when nothing changed | Only fires when something happens |
| Delays depend on poll interval        | Near-instant notifications        |
| Simple but inefficient                | Efficient and scalable            |

Webhooks are the preferred approach for production integrations where you need to react to events in real-time.

## Available Event Types

Airweave publishes events across three lifecycle domains:

### Sync Events

| Event            | Description                    | When it fires                    |
| ---------------- | ------------------------------ | -------------------------------- |
| `sync.pending`   | Sync job queued                | Job created and waiting to start |
| `sync.running`   | Sync job started               | Job begins processing            |
| `sync.completed` | Sync job finished successfully | All data synced without errors   |
| `sync.failed`    | Sync job failed                | Job encountered an error         |
| `sync.cancelled` | Sync job cancelled             | Job was manually cancelled       |

### Source Connection Events

| Event                              | Description               | When it fires                                                 |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------- |
| `source_connection.created`        | Connection record created | New source connection added (may or may not be authenticated) |
| `source_connection.auth_completed` | OAuth flow completed      | Connection is now authenticated and ready to use              |
| `source_connection.deleted`        | Connection removed        | Source connection and associated data deleted                 |

### Collection Events

| Event                | Description                   | When it fires                              |
| -------------------- | ----------------------------- | ------------------------------------------ |
| `collection.created` | New collection created        | A new collection is set up                 |
| `collection.updated` | Collection properties changed | Collection name or configuration modified  |
| `collection.deleted` | Collection removed            | Collection and all associated data deleted |

Most integrations only need `sync.completed` and `sync.failed`. Subscribe to source connection and collection events if you need to track infrastructure changes, for example, to audit when connections are added or removed, or to react when collections are created.

## How It Works

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Airweave  │ ──── │    Svix     │ ──── │ Your Server │
│  (Events)   │      │  (Delivery) │      │  (Webhook)  │
└─────────────┘      └─────────────┘      └─────────────┘
```

1. **Something happens.** A sync job completes, a source connection is created, or a collection is updated.
2. **Airweave creates an event.** The event is recorded with full payload data.
3. **Svix delivers it.** Our webhook infrastructure (powered by [Svix](https://www.svix.com/)) sends an HTTP POST to your registered endpoints.
4. **You process it.** Your server receives the payload and takes action.

Svix handles retries, delivery guarantees, and signs every outbound delivery. You verify signatures on your end using the signing secret (see the [Setup Guide](/webhooks/setup) for examples).

## Use Cases

#### Trigger Workflows

Start a data pipeline, refresh a cache, or kick off downstream processing when a sync completes.

#### Send Alerts

Notify your team via Slack, email, or PagerDuty when a sync fails or a connection is removed.

#### Track Infrastructure Changes

Know the moment a source connection is added, authenticated, or deleted, or when collections change.

#### Audit & Logging

Record every lifecycle event to your own logging system for compliance or debugging.

## Quick Example

Here's what a webhook delivery looks like when a sync completes:

**HTTP Request to your endpoint:**

```http
POST /webhooks/airweave HTTP/1.1
Host: your-server.com
Content-Type: application/json
svix-id: msg_2xKvB8LPqM4nRst
svix-timestamp: 1705329000
svix-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "event_type": "sync.completed",
  "sync_id": "440e8400-e29b-41d4-a716-446655440099",
  "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
  "collection_id": "770e8400-e29b-41d4-a716-446655440002",
  "collection_readable_id": "sales-data-ab123",
  "collection_name": "Sales Data",
  "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
  "source_type": "salesforce",
  "entities_inserted": 42,
  "entities_updated": 10,
  "entities_deleted": 3,
  "entities_skipped": 120,
  "chunks_written": 215,
  "timestamp": "2025-01-15T14:30:00Z"
}
```

Your server responds with `200 OK` to acknowledge receipt.

## Next Steps

#### [Types & Formats](/webhooks/types-and-formats)

Learn the detailed structure of event payloads and delivery format.

#### [Setup Guide](/webhooks/setup)

Create your first webhook subscription and start receiving events.