---
title: "Create Subscription"
method: POST
path: "/webhooks/subscriptions"
tags: ["webhooks"]
---

# Create Subscription

`POST /webhooks/subscriptions`

## Request

- Base URL: `https://api.airweave.ai`
- URL: `https://api.airweave.ai/webhooks/subscriptions`
- Auth: API key in header `x-api-key`

Create a new webhook subscription.

Webhook subscriptions allow you to receive real-time notifications when events
occur in Airweave. When you create a subscription, you specify:

- **URL**: The HTTPS endpoint where events will be delivered
- **Event Types**: Which events you want to receive (e.g., `sync.completed`, `sync.failed`)
- **Secret** (optional): A custom signing secret for verifying webhook signatures

After creation, Airweave will send HTTP POST requests to your URL whenever
matching events occur. Each request includes a signature header for verification.

## Request body

- CreateSubscriptionRequest: Create a new webhook subscription. Webhook subscriptions define where Airweave should send event notifications. You can subscribe to specific event types to receive only the events you care about.
  - `url` string, uri, required: The HTTPS URL where webhook events will be delivered. Must be a publicly accessible endpoint that returns a 2xx status code.
  - `event_types` EventType[], required: List of event types to subscribe to. Events not in this list will not be delivered to this subscription. Available types: `sync.pending`, `sync.running`, `sync.completed`, `sync.failed`, `sync.cancelled`, `source_connection.created`, `source_connection.auth_completed`, `source_connection.deleted`, `collection.created`, `collection.updated`, `collection.deleted`.
  - `secret` string, nullable: Optional custom signing secret for webhook signature verification. If not provided, a secure secret will be auto-generated. Must be at least 24 characters if specified.

## Response `200`

Created subscription

- WebhookSubscription: A webhook subscription (endpoint) configuration. This is the lightweight representation returned by list, create, update, and delete endpoints. For the full detail view (delivery attempts, signing secret) see ``WebhookSubscriptionDetail``.
  - `id` string, required: Unique identifier for this subscription (UUID format)
  - `url` string, required: The URL where webhook events are delivered
  - `filter_types` string[], nullable: Event types this subscription is filtered to receive. See EventType enum for all available types.
  - `disabled` boolean: Whether this subscription is currently disabled. Disabled subscriptions do not receive event deliveries.
  - `description` string, nullable: Optional human-readable description of this subscription
  - `created_at` string, date-time, required: When this subscription was created (ISO 8601 format, UTC)
  - `updated_at` string, date-time, required: When this subscription was last updated (ISO 8601 format, UTC)
  - `health_status` 'healthy' | 'degraded' | 'failing' | 'unknown': Health status of a webhook subscription based on recent delivery attempts.

## Other responses

- `422`: Validation Error
- `429`: Rate Limit Exceeded

## Changes

> 63 revisions in range; 2 not diffed.

- **2026-03-22** `a8105b372b4d`: 6 info
  - added the new `search.completed` enum value to the request property `event_types/items/`
  - added the new `search.failed` enum value to the request property `event_types/items/`
  - added the new `search.reranking` enum value to the request property `event_types/items/`
  - added the new `search.started` enum value to the request property `event_types/items/`
  - …2 more
- **2026-03-12** `a944d305e967`: 2 warning, 8 info
  - removed the optional property `delivery_attempts` from the response with the `200` status
  - removed the optional property `secret` from the response with the `200` status
  - added the new `access_control.batch_processed` enum value to the request property `event_types/items/`
  - added the new `entity.batch_processed` enum value to the request property `event_types/items/`
  - …6 more
- **2026-02-14** `dcef44679b67`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/airweave-ai/apis/airweave/changes/webhooks/subscriptions/post.md)

---

[API](https://skmtc.dev/airweave-ai/apis/airweave.md) - [All operations](https://skmtc.dev/airweave-ai/apis/airweave/llms.txt) - [OpenAPI document](https://skmtc.dev/airweave-ai/apis/airweave/revisions/bf410c28c0c6?raw)