@devries-cameron20 / composio Mirror · read-only / commits / 601e557e9
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 17:00 UTC

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 +