Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
chore: lookahead changelog for webhook payload versions of new orgs
Composio committed
Dec 29, 2025 at 18:38 UTC
601e557e92d40c296e35a790d6a0b69fd86f24db
1 file changed
+158
fern/pages/src/changelog/12-30-25.md
new
+158
@@ -0,0 +1,158 @@
1
+---
2
+title: "Lookahead: Webhook Payload V3 - Enhanced Structure & Standards"
3
+description: "Announcing upcoming improvements to webhook payloads with better structure, metadata separation, and industry-standard compliance"
4
+---
5
+
6
+## 🔮 Lookahead Announcement
7
+
8
+We're introducing **Webhook Payload V3** - a redesigned webhook structure that follows industry standards and provides better developer experience. This update affects how you receive trigger events via webhooks and Pusher.
9
+
10
+## What's Changing?
11
+
12
+### New Webhook Structure
13
+
14
+We're adopting the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) for better consistency and reliability.
15
+
16
+#### Headers
17
+A new header will identify the webhook version:
18
+```
19
+x-composio-webhook-version: V3
20
+```
21
+
22
+#### Payload Structure
23
+The payload structure is being reorganized to separate Composio metadata from trigger data:
24
+
25
+**Before (V2):**
26
+```json
27
+{
28
+ "log_id": "log_TpxVOLXYnwXZ",
29
+ "timestamp": "2025-12-23T13:06:07.695Z",
30
+ "type": "gmail_new_gmail_message",
31
+ "data": {
32
+ "connection_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
33
+ "connection_nano_id": "ca_xYz9AbCdEfGh",
34
+ "trigger_nano_id": "ti_JZFoTyYKbzhB",
35
+ "trigger_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
36
+ "user_id": "usr-demo-12a3b4c5...",
37
+ // ... actual trigger data mixed with metadata
38
+ }
39
+}
40
+```
41
+
42
+**After (V3):**
43
+```json
44
+{
45
+ "id": "msg_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
46
+ "timestamp": "2025-12-23T13:06:07.695Z",
47
+ "type": "composio.trigger.message",
48
+ "metadata": {
49
+ "log_id": "log_TpxVOLXYnwXZ",
50
+ "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",
51
+ "auth_config_id": "ac_aCYTppZ5RsRc",
52
+ "connected_account_id": "ca_cATYssZ5RrSc",
53
+ "trigger_id": "ti_JZFoTyYKbzhB",
54
+ "user_id": "pg-test-86c9fc84..."
55
+ },
56
+ "data": {
57
+ // Clean trigger data without Composio metadata
58
+ }
59
+}
60
+```
61
+
62
+### Key Improvements
63
+
64
+1. **Metadata Separation**: Composio-specific fields (connection IDs, trigger IDs, user IDs) are now in a dedicated `metadata` object
65
+2. **Clean Data**: The `data` field now contains only the actual trigger payload without infrastructure metadata
66
+3. **Standardized Type Field**: The `type` field now follows a consistent format (`composio.trigger.message`) instead of trigger-specific names like `gmail_new_gmail_message`
67
+4. **Trigger Slug in Metadata**: The trigger slug (e.g., `GMAIL_NEW_GMAIL_MESSAGE`) is now available in `metadata.trigger_slug` for easy identification
68
+5. **Standards Compliance**: Follows Standard Webhooks specification for better interoperability
69
+6. **Consistent Structure**: Same payload structure for both webhooks and Pusher channels
70
+
71
+## Migration Guide
72
+
73
+### Updating Your Webhook Handlers
74
+
75
+If you're accessing Composio metadata fields, update your code:
76
+
77
+```python
78
+# Before (V2)
79
+trigger_type = payload["type"] # "gmail_new_gmail_message"
80
+connection_id = payload["data"]["connection_id"]
81
+trigger_id = payload["data"]["trigger_id"]
82
+message_text = payload["data"]["message_text"]
83
+
84
+# After (V3)
85
+trigger_type = payload["type"] # "composio.trigger.message"
86
+trigger_slug = payload["metadata"]["trigger_slug"] # "GMAIL_NEW_GMAIL_MESSAGE"
87
+connection_id = payload["metadata"]["connected_account_id"]
88
+trigger_id = payload["metadata"]["trigger_id"]
89
+message_text = payload["data"]["message_text"]
90
+```
91
+
92
+```typescript
93
+// Before (V2)
94
+const triggerSlug = payload.type; // "gmail_new_gmail_message"
95
+const connectionId = payload.data.connection_id;
96
+const triggerId = payload.data.trigger_id;
97
+const messageText = payload.data.message_text;
98
+
99
+// After (V3)
100
+const webhookType = payload.type; // "composio.trigger.message"
101
+const triggerSlug = payload.metadata.trigger_slug; // "GMAIL_NEW_GMAIL_MESSAGE"
102
+const connectionId = payload.metadata.connected_account_id;
103
+const triggerId = payload.metadata.trigger_id;
104
+const messageText = payload.data.message_text;
105
+```
106
+
107
+### Checking Webhook Version
108
+
109
+You can detect the webhook version from headers:
110
+
111
+```python
112
+webhook_version = headers.get("x-composio-webhook-version", "V2")
113
+if webhook_version == "V3":
114
+ # Use new structure
115
+ metadata = payload["metadata"]
116
+else:
117
+ # Use old structure
118
+ metadata = payload["data"]
119
+```
120
+
121
+## Rollout Timeline
122
+
123
+- **December 2025**: V3 released, opt-in via project settings
124
+- **February 15, 2026**: All new organizations will default to V3
125
+- **Existing organizations**: Continue using V2 by default, can opt-in to V3 anytime
126
+
127
+## How to Opt-In
128
+
129
+1. Go to your project settings in the Composio dashboard
130
+2. Navigate to the Webhooks section
131
+3. Select "Webhook Payload Version: V3"
132
+4. Update your webhook handlers to use the new structure
133
+5. Test thoroughly before enabling in production
134
+
135
+<Note>
136
+Organizations created **before February 15, 2026** will remain on V2 by default. You can switch to V3 at your convenience.
137
+
138
+Organizations created **on or after February 15, 2026** will use V3 by default.
139
+</Note>
140
+
141
+## Benefits
142
+
143
+- **Better DX**: Clear separation between metadata and actual trigger data
144
+- **Standards Compliance**: Follows industry-standard webhook specifications
145
+- **Consistency**: Same structure across webhooks and Pusher channels
146
+- **Future-Proof**: Built on established standards for long-term compatibility
147
+
148
+## Need Help?
149
+
150
+If you have questions about migrating to V3 or need assistance:
151
+- Join our [Discord community](https://discord.gg/composio)
152
+- Check our [documentation](https://docs.composio.dev)
153
+- Contact support at support@composio.dev
154
+
155
+---
156
+
157
+*This is a lookahead announcement. Actual release dates and features may vary slightly.*
158
+