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

# Create Subscription

`POST /webhooks/subscriptions`

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

---

[API](https://skmtc.net/airweave-ai/apis/airweave.md) · [All operations](https://skmtc.net/airweave-ai/apis/airweave/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airweave-ai/airweave/versions/bf410c28c0c6/schema)