Webhooks Overview

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)  │
└─────────────┘      └─────────────┘      └─────────────┘

Something happens. A sync job completes, a source connection is created, or a collection is updated.
Airweave creates an event. The event is recorded with full payload data.
Svix delivers it. Our webhook infrastructure (powered by Svix) sends an HTTP POST to your registered endpoints.
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 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:

1 POST /webhooks/airweave HTTP/1.1
2 Host: your-server.com
3 Content-Type: application/json
4 svix-id: msg_2xKvB8LPqM4nRst
5 svix-timestamp: 1705329000
6 svix-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
7 
8 {
9   "event_type": "sync.completed",
10   "sync_id": "440e8400-e29b-41d4-a716-446655440099",
11   "sync_job_id": "550e8400-e29b-41d4-a716-446655440000",
12   "collection_id": "770e8400-e29b-41d4-a716-446655440002",
13   "collection_readable_id": "sales-data-ab123",
14   "collection_name": "Sales Data",
15   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
16   "source_type": "salesforce",
17   "entities_inserted": 42,
18   "entities_updated": 10,
19   "entities_deleted": 3,
20   "entities_skipped": 120,
21   "chunks_written": 215,
22   "timestamp": "2025-01-15T14:30:00Z"
23 }

Your server responds with 200 OK to acknowledge receipt.

Next Steps

Types & Formats

Learn the detailed structure of event payloads and delivery format.

Setup Guide

Create your first webhook subscription and start receiving events.