@devries-cameron20 / composio-1 / commits / 3e180b74e
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add webhook subscriptions API changelog

- New Webhook Subscriptions API with event filtering - New composio.connected_account.expired event (V3 only) - Deprecation of legacy webhook endpoints - Auto-migration for existing users Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Anshu Garg committed Feb 6, 2026 at 13:40 UTC 3e180b74e0df4324361680d3ec86f0292bc03109
1 file changed +281
docs/content/changelog/02-06-26-webhook-subscriptions-api.mdx new
+281
@@ -0,0 +1,281 @@
1 +---
2 +title: "Webhook Subscriptions API"
3 +description: "New API for managing webhook configurations with event filtering, HMAC signature verification, and platform lifecycle events"
4 +date: "2026-02-06"
5 +---
6 +
7 +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.
8 +
9 +## Summary
10 +
11 +| Change | Type | Action Required |
12 +|--------|------|-----------------|
13 +| New Webhook Subscriptions API | New Feature | No |
14 +| `composio.connected_account.expired` event | New Feature | Opt-in |
15 +| Legacy webhook endpoints | Deprecated | Migration recommended |
16 +| `webhook_url`, `webhook_secret` in Project | Deprecated | Use new API |
17 +
18 +---
19 +
20 +## New Webhook Subscriptions API
21 +
22 +A dedicated API for creating and managing webhook endpoints with granular event filtering.
23 +
24 +### Endpoints
25 +
26 +| Method | Endpoint | Description |
27 +|--------|----------|-------------|
28 +| `POST` | `/api/v3/webhook_subscriptions` | Create a subscription |
29 +| `GET` | `/api/v3/webhook_subscriptions` | List all subscriptions |
30 +| `GET` | `/api/v3/webhook_subscriptions/{id}` | Get subscription details |
31 +| `PATCH` | `/api/v3/webhook_subscriptions/{id}` | Update subscription |
32 +| `DELETE` | `/api/v3/webhook_subscriptions/{id}` | Delete subscription |
33 +| `POST` | `/api/v3/webhook_subscriptions/{id}/rotate_secret` | Rotate signing secret |
34 +| `GET` | `/api/v3/webhook_subscriptions/event_types` | List available event types |
35 +
36 +### Key Capabilities
37 +
38 +- **Event filtering**: Subscribe only to events you need
39 +- **HMAC-SHA256 signatures**: Every webhook includes a cryptographic signature for verification
40 +- **Secret rotation**: Rotate signing secrets without downtime
41 +- **Version control**: Choose payload format version (V1, V2, V3)
42 +
43 +### Creating a Subscription
44 +
45 +```bash
46 +curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
47 + -H "x-api-key: YOUR_API_KEY" \
48 + -H "Content-Type: application/json" \
49 + -d '{
50 + "webhook_url": "https://your-server.com/webhooks/composio",
51 + "enabled_events": ["composio.trigger.message"],
52 + "version": "V3"
53 + }'
54 +```
55 +
56 +**Response:**
57 +
58 +```json
59 +{
60 + "id": "whs_abc123xyz",
61 + "webhook_url": "https://your-server.com/webhooks/composio",
62 + "version": "V3",
63 + "enabled_events": ["composio.trigger.message"],
64 + "secret": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
65 + "created_at": "2026-02-06T12:00:00.000Z",
66 + "updated_at": "2026-02-06T12:00:00.000Z"
67 +}
68 +```
69 +
70 +<Callout type="warn">
71 +The `secret` is only returned once at creation time or when rotated. Store it securely for signature verification.
72 +</Callout>
73 +
74 +### Requirements
75 +
76 +- **1 subscription per project**: Currently limited to one webhook subscription per project. This will be expanded in future releases.
77 +- **HTTPS required**: Webhook URLs must use HTTPS in production environments.
78 +
79 +---
80 +
81 +## New Event: `composio.connected_account.expired`
82 +
83 +A new platform event that notifies you when a connected account's authentication expires and cannot be automatically refreshed.
84 +
85 +<Callout type="info">
86 +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.
87 +</Callout>
88 +
89 +### Use Cases
90 +
91 +- Prompt users to re-authenticate before workflows fail
92 +- Track connection health across your user base
93 +- Automate re-connection flows
94 +- Build proactive notification systems
95 +
96 +### Subscribing to Connection Expiry Events
97 +
98 +```bash
99 +curl -X POST "https://backend.composio.dev/api/v3/webhook_subscriptions" \
100 + -H "x-api-key: YOUR_API_KEY" \
101 + -H "Content-Type: application/json" \
102 + -d '{
103 + "webhook_url": "https://your-server.com/webhooks/composio",
104 + "enabled_events": [
105 + "composio.trigger.message",
106 + "composio.connected_account.expired"
107 + ],
108 + "version": "V3"
109 + }'
110 +```
111 +
112 +### Payload Structure
113 +
114 +The `composio.connected_account.expired` event follows the V3 envelope format:
115 +
116 +```json
117 +{
118 + "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
119 + "timestamp": "2026-02-06T12:00:00.000Z",
120 + "type": "composio.connected_account.expired",
121 + "metadata": {
122 + "project_id": "pr_abc123",
123 + "org_id": "org_xyz789"
124 + },
125 + "data": {
126 + "toolkit": {
127 + "slug": "gmail"
128 + },
129 + "auth_config": {
130 + "id": "ac_def456",
131 + "auth_scheme": "OAUTH2",
132 + "is_composio_managed": true,
133 + "is_disabled": false
134 + },
135 + "id": "ca_ghi789",
136 + "status": "EXPIRED",
137 + "created_at": "2025-12-01T10:00:00.000Z",
138 + "updated_at": "2026-02-06T12:00:00.000Z",
139 + "status_reason": "OAuth refresh token expired",
140 + "is_disabled": false
141 + }
142 +}
143 +```
144 +
145 +<Callout type="info">
146 +The `data` object matches the response from [`GET /api/v3/connected_accounts/{id}`](https://docs.composio.dev/api-reference/connected-accounts/get-a-specific-connected-account), making it easy to process with existing code and SDK types.
147 +</Callout>
148 +
149 +### Key Fields
150 +
151 +| Field | Description |
152 +|-------|-------------|
153 +| `id` | Unique event identifier |
154 +| `timestamp` | ISO 8601 timestamp when the event was generated |
155 +| `type` | Always `composio.connected_account.expired` for this event |
156 +| `metadata.project_id` | Your project identifier |
157 +| `metadata.org_id` | Your organization identifier |
158 +| `data.id` | The connected account ID (use this to prompt re-authentication) |
159 +| `data.toolkit.slug` | The integration that expired (e.g., `gmail`, `slack`) |
160 +| `data.status` | Will be `EXPIRED` |
161 +| `data.status_reason` | Human-readable reason for expiration |
162 +
163 +---
164 +
165 +## Verifying Webhook Signatures
166 +
167 +All webhooks include an HMAC signature in the `webhook-signature` header. Use the SDK's built-in verification functions or see the [Triggers documentation](https://docs.composio.dev/docs/triggers) for implementation details.
168 +
169 +---
170 +
171 +## Available Event Types
172 +
173 +Query available events and their version compatibility:
174 +
175 +```bash
176 +curl "https://backend.composio.dev/api/v3/webhook_subscriptions/event_types" \
177 + -H "x-api-key: YOUR_API_KEY"
178 +```
179 +
180 +| Event Type | Description | Supported Versions |
181 +|------------|-------------|-------------------|
182 +| `composio.trigger.message` | Trigger events from integrations | V1, V2, V3 |
183 +| `composio.connected_account.expired` | Connection authentication expired | **V3 only** |
184 +
185 +---
186 +
187 +## Deprecations
188 +
189 +### Deprecated Endpoints
190 +
191 +The following legacy endpoints are deprecated and will be removed in a future release:
192 +
193 +| Deprecated Endpoint | Replacement |
194 +|---------------------|-------------|
195 +| `GET /api/v3/org/project/webhook` | `GET /api/v3/webhook_subscriptions` |
196 +| `POST /api/v3/org/project/webhook/update` | `POST /api/v3/webhook_subscriptions` |
197 +| `DELETE /api/v3/org/project/webhook` | `DELETE /api/v3/webhook_subscriptions/{id}` |
198 +| `POST /api/v3/org/project/webhook/refresh` | `POST /api/v3/webhook_subscriptions/{id}/rotate_secret` |
199 +
200 +### Deprecated Fields in Project Response
201 +
202 +| Field | Status | Notes |
203 +|-------|--------|-------|
204 +| `webhook_url` | Deprecated | Use Webhook Subscriptions API |
205 +| `webhook_secret` | Deprecated | Use Webhook Subscriptions API |
206 +| `event_webhook_url` | Deprecated | Never implemented |
207 +| `is_new_webhook` | Deprecated | Use Webhook Subscriptions API |
208 +
209 +---
210 +
211 +## Backward Compatibility
212 +
213 +<Callout type="warn">
214 +**No immediate action required.** Your existing webhook configurations will continue to work.
215 +</Callout>
216 +
217 +### What We've Done For You
218 +
219 +- **Automatic migration**: We've created a webhook subscription for all existing projects that had webhook URLs configured
220 +- **No duplicate deliveries**: Legacy and new systems don't send duplicate webhooks
221 +- **Same payload format**: If you were using V1, V2, or V3 triggers, they continue with the same format
222 +
223 +### What Continues to Work
224 +
225 +- Legacy webhook endpoints (deprecated but functional)
226 +- Existing project webhook configurations
227 +- All existing trigger payload formats (V1, V2, V3)
228 +- Signature verification with your existing secret
229 +
230 +### Recommended Actions
231 +
232 +While not required, we recommend migrating to benefit from:
233 +
234 +1. **Event filtering**: Only receive events you care about
235 +2. **New events**: Access `composio.connected_account.expired` (V3 only)
236 +3. **Better secret management**: Rotate secrets without downtime
237 +4. **Future features**: New events will only be available via subscriptions
238 +
239 +---
240 +
241 +## Migration Guide
242 +
243 +Your existing webhook configuration has been automatically migrated. No action is required for your webhooks to continue working.
244 +
245 +### Using the New API
246 +
247 +Start using the new endpoints instead of the legacy ones:
248 +
249 +```bash
250 +# List your webhook subscriptions
251 +curl "https://backend.composio.dev/api/v3/webhook_subscriptions" \
252 + -H "x-api-key: YOUR_API_KEY"
253 +```
254 +
255 +### (Optional) Enable New Events
256 +
257 +Add `composio.connected_account.expired` to receive connection expiry notifications:
258 +
259 +```bash
260 +curl -X PATCH "https://backend.composio.dev/api/v3/webhook_subscriptions/{id}" \
261 + -H "x-api-key: YOUR_API_KEY" \
262 + -H "Content-Type: application/json" \
263 + -d '{
264 + "enabled_events": [
265 + "composio.trigger.message",
266 + "composio.connected_account.expired"
267 + ]
268 + }'
269 +```
270 +
271 +---
272 +
273 +## Payload Version Comparison
274 +
275 +| Version | Format | Recommendation |
276 +|---------|--------|----------------|
277 +| V1 | Legacy flat structure | For backward compatibility only |
278 +| V2 | Nested with metadata | For existing integrations |
279 +| **V3** | Modern envelope format | **Recommended for all new integrations** |
280 +
281 +V3 follows industry standards with a consistent envelope containing `id`, `timestamp`, `type`, `metadata`, and `data`.