---
title: "Update Subscription"
method: PATCH
path: "/webhooks/subscriptions/{subscription_id}"
tags: ["webhooks"]
---

# Update Subscription

`PATCH /webhooks/subscriptions/{subscription_id}`

## Request

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

Update an existing webhook subscription.

Use this endpoint to modify a subscription's configuration. You can:

- **Change the URL**: Update where events are delivered
- **Update event types**: Modify which events trigger notifications
- **Enable/disable**: Temporarily pause delivery without deleting the subscription
- **Recover messages**: When re-enabling, optionally recover missed messages

Only include the fields you want to change. Omitted fields will retain their
current values.

When re-enabling a subscription (`disabled: false`), you can optionally provide
`recover_since` to automatically retry all messages that were generated while
the subscription was disabled.

## Path parameters

- `subscription_id` string, required: The unique identifier of the subscription to update (UUID).

## Request body

- PatchSubscriptionRequest: Update an existing webhook subscription. All fields are optional. Only provided fields will be updated; omitted fields retain their current values. When re-enabling a subscription (setting `disabled: false`), you can optionally provide `recover_since` to replay messages that were missed while disabled.
  - `url` string, uri, nullable: New URL for webhook delivery. Must be a publicly accessible HTTPS endpoint.
  - `event_types` EventType[], nullable: New list of event types to subscribe to. This replaces the existing list entirely.
  - `disabled` boolean, nullable: Set to `true` to pause delivery to this subscription, or `false` to resume. Disabled subscriptions will not receive events.
  - `recover_since` string, date-time, nullable: When re-enabling a subscription (`disabled: false`), optionally recover failed messages from this timestamp. Only applies when enabling.

## Response `200`

Updated 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

- `404`: Subscription Not Found
- `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/anyOf[subschema #1]/items/`
  - added the new `search.failed` enum value to the request property `event_types/anyOf[subschema #1]/items/`
  - added the new `search.reranking` enum value to the request property `event_types/anyOf[subschema #1]/items/`
  - added the new `search.started` enum value to the request property `event_types/anyOf[subschema #1]/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/anyOf[subschema #1]/items/`
  - added the new `entity.batch_processed` enum value to the request property `event_types/anyOf[subschema #1]/items/`
  - …6 more
- **2026-02-14** `dcef44679b67`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/airweave-ai/apis/airweave/changes/webhooks/subscriptions/:subscription_id/patch.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)