[PLEN-1437] docs: Webhook Subscriptions API changelog (#2581)

Author: anshugarg15

docs/content/changelog/02-06-26-webhook-subscriptions-api.mdx

@@ -0,0 +1,222 @@
+---
+title: "Webhook Subscriptions API & Connection Expiry Events"
+description: "New API for managing webhook configurations with event filtering, plus a new event to notify when connected accounts expire"
+date: "2026-02-06"
+---
+
+A new API for managing webhook configurations with event filtering, HMAC signature verification, and support for platform lifecycle events. This replaces the legacy project-level webhook settings with a more flexible, subscription-based model.
+
+## Summary
+
+| Change | Type | Action Required |
+|--------|------|-----------------|
+| New Webhook Subscriptions API | New Feature | No |
+| `composio.connected_account.expired` event | New Feature | Opt-in |
+| Legacy webhook endpoints | Deprecated | Migration recommended |
+| `webhook_url`, `webhook_secret` in Project | Deprecated | Use new API |
+
+---
+
+## API Overview
+
+See the [API Reference](/reference/api-reference/webhooks) for complete details.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v3/webhook_subscriptions` | Create a subscription |
+| `GET` | `/api/v3/webhook_subscriptions` | List all subscriptions |
+| `GET` | `/api/v3/webhook_subscriptions/{id}` | Get subscription details |
+| `PATCH` | `/api/v3/webhook_subscriptions/{id}` | Update subscription |
+| `DELETE` | `/api/v3/webhook_subscriptions/{id}` | Delete subscription |
+| `POST` | `/api/v3/webhook_subscriptions/{id}/rotate_secret` | Rotate signing secret |
+| `GET` | `/api/v3/webhook_subscriptions/event_types` | List available event types |
+
+### Key Capabilities
+
+- **Event filtering**: Subscribe only to events you need
+- **HMAC-SHA256 signatures**: Every webhook includes a cryptographic signature for verification
+- **Secret rotation**: Rotate signing secrets on demand
+
+### Creating a Subscription
+
+```bash
+curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "webhook_url": "https://your-server.com/webhooks/composio",
+    "enabled_events": ["composio.trigger.message"],
+    "version": "V3"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "id": "ws_your-subscription-id",
+  "webhook_url": "https://your-server.com/webhooks/composio",
+  "version": "V3",
+  "enabled_events": ["composio.trigger.message"],
+  "secret": "<your-webhook-secret>",
+  "created_at": "2026-02-06T12:00:00.000Z",
+  "updated_at": "2026-02-06T12:00:00.000Z"
+}
+```
+
+<Callout type="warn">
+The `secret` is only returned once at creation time or when rotated. Store it securely for signature verification.
+</Callout>
+
+### Notes
+
+- **1 subscription per project**: Currently limited to one webhook subscription per project. This will be expanded in future releases.
+- **HTTPS required**: Webhook URLs must use HTTPS in production environments.
+
+---
+
+## New Event: `composio.connected_account.expired`
+
+A new platform event that notifies you when an **OAuth2** connected account's authentication expires and cannot be automatically refreshed.
+
+<Callout type="info">
+This event is **only available in V3 format**. We strongly recommend using V3 for all new integrations to access the latest features and follow standard webhook practices.
+</Callout>
+
+### Use Cases
+
+- Prompt users to re-authenticate before workflows fail
+- Track connection health across your user base
+- Automate re-connection flows
+- Build proactive notification systems
+
+### Subscribing to Connection Expiry Events
+
+```bash
+curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "webhook_url": "https://your-server.com/webhooks/composio",
+    "enabled_events": [
+      "composio.trigger.message",
+      "composio.connected_account.expired"
+    ],
+    "version": "V3"
+  }'
+```
+
+### Payload Structure
+
+The `composio.connected_account.expired` event follows the V3 envelope format:
+
+```json
+{
+  "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
+  "timestamp": "2026-02-06T12:00:00.000Z",
+  "type": "composio.connected_account.expired",
+  "metadata": {
+    "project_id": "pr_your-project-id",
+    "org_id": "ok_your-org-id"
+  },
+  "data": {
+    "toolkit": {
+      "slug": "gmail"
+    },
+    "auth_config": {
+      "id": "ac_your-auth-config-id",
+      "auth_scheme": "OAUTH2",
+      "is_composio_managed": true,
+      "is_disabled": false
+    },
+    "id": "ca_your-connected-account-id",
+    "status": "EXPIRED",
+    "created_at": "2025-12-01T10:00:00.000Z",
+    "updated_at": "2026-02-06T12:00:00.000Z",
+    "status_reason": "OAuth refresh token expired",
+    "is_disabled": false
+  }
+}
+```
+
+<Callout type="info">
+The `data` object matches the response from [`GET /api/v3/connected_accounts/{id}`](/reference/api-reference/connected-accounts/getConnectedAccountsByNanoid), making it easy to process with existing code and SDK types.
+</Callout>
+
+---
+
+## Verifying Webhook Signatures
+
+All webhooks include an HMAC signature in the `webhook-signature` header. Use the SDK's built-in verification functions or see the [Triggers documentation](/docs/triggers) for implementation details.
+
+---
+
+## Available Event Types
+
+Query available events and their version compatibility:
+
+```bash
+curl "https://backend.composio.dev/api/v3/webhook_subscriptions/event_types" \
+  -H "x-api-key: YOUR_API_KEY"
+```
+
+| Event Type | Description | Supported Versions |
+|------------|-------------|-------------------|
+| `composio.trigger.message` | Trigger events from integrations | V1, V2, V3 |
+| `composio.connected_account.expired` | Connection authentication expired | **V3 only** |
+
+---
+
+## Deprecations
+
+### Deprecated Endpoints
+
+The following legacy endpoints are deprecated and will be removed in a future release:
+
+| Deprecated Endpoint | Replacement |
+|---------------------|-------------|
+| `GET /api/v3/org/project/webhook` | `GET /api/v3/webhook_subscriptions` |
+| `POST /api/v3/org/project/webhook/update` | `POST /api/v3/webhook_subscriptions` |
+| `DELETE /api/v3/org/project/webhook` | `DELETE /api/v3/webhook_subscriptions/{id}` |
+| `POST /api/v3/org/project/webhook/refresh` | `POST /api/v3/webhook_subscriptions/{id}/rotate_secret` |
+
+### Deprecated Fields in Project Response
+
+| Field | Status | Notes |
+|-------|--------|-------|
+| `webhook_url` | Deprecated | Use Webhook Subscriptions API |
+| `webhook_secret` | Deprecated | Use Webhook Subscriptions API |
+| `event_webhook_url` | Deprecated | Never implemented |
+| `is_new_webhook` | Deprecated | Use Webhook Subscriptions API |
+
+---
+
+## Backward Compatibility
+
+<Callout type="warn">
+**No immediate action required.** Your existing webhook configurations will continue to work.
+</Callout>
+
+### What We've Done For You
+
+- **Automatic migration**: We've created a webhook subscription for all existing projects that had webhook URLs configured, with `composio.trigger.message` enabled by default
+- **Same payload format**: If you were using V1, V2, or V3 triggers, they continue with the same format
+
+### What Continues to Work
+
+- Legacy webhook endpoints (deprecated but functional)
+- Existing project webhook configurations
+- All existing trigger payload formats (V1, V2, V3)
+- Signature verification with your existing secret
+
+---
+
+## Payload Version Comparison
+
+| Version | Format | Recommendation |
+|---------|--------|----------------|
+| V1 | Legacy flat structure | For backward compatibility only |
+| V2 | Nested with metadata | For existing integrations |
+| **V3** | Structured envelope with `id`, `timestamp`, `type`, `metadata`, `data` | **Recommended for all new integrations** |