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. Instead of constantly polling the API to check if a sync completed, 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

All events are related to sync job lifecycle:

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

Most integrations only need sync.completed and sync.failed. Subscribe to additional events if you need granular progress tracking.

How It Works

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

Something happens — A sync job completes, fails, or changes state
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, signature verification, and delivery guarantees so you don’t have to build that infrastructure yourself.

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.

Update Dashboards

Push real-time sync status to monitoring dashboards or admin panels.

Audit & Logging

Record every sync 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   "job_id": "550e8400-e29b-41d4-a716-446655440000",
11   "collection_readable_id": "sales-data-ab123",
12   "collection_name": "Sales Data",
13   "source_connection_id": "660e8400-e29b-41d4-a716-446655440001",
14   "source_type": "salesforce",
15   "status": "completed",
16   "timestamp": "2025-01-15T14:30:00Z"
17 }

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.