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

---
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 [Webhook Subscriptions API Reference](/reference/api-reference/webhook-subscriptions) 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** |