Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 10:45 UTC
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`.