@devries-cameron20 / composio Mirror · read-only
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 21, 03:37 UTC

next
mdx 153 lines 5.27 KB
Raw
1 ---
2 title: "Webhook Payload V3 - Lookahead Announcement"
3 description: "Redesigned webhook structure following Standard Webhooks specification"
4 date: "2025-12-30"
5 ---
6
7 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.
8
9 ## What's Changing?
10
11 ### New Webhook Structure
12
13 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.
14
15 #### Headers
16 A new header will identify the webhook version:
17 ```
18 x-composio-webhook-version: V3
19 ```
20
21 #### Payload Structure
22 The payload structure is being reorganized to separate Composio metadata from trigger data:
23
24 **Before (V2):**
25 ```json
26 {
27 "log_id": "log_TpxVOLXYnwXZ",
28 "timestamp": "2025-12-23T13:06:07.695Z",
29 "type": "gmail_new_gmail_message",
30 "data": {
31 "connection_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
32 "connection_nano_id": "ca_xYz9AbCdEfGh",
33 "trigger_nano_id": "ti_JZFoTyYKbzhB",
34 "trigger_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
35 "user_id": "usr-demo-12a3b4c5...",
36 // ... actual trigger data mixed with metadata
37 }
38 }
39 ```
40
41 **After (V3):**
42 ```json
43 {
44 "id": "msg_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
45 "timestamp": "2025-12-23T13:06:07.695Z",
46 "type": "composio.trigger.message",
47 "metadata": {
48 "log_id": "log_TpxVOLXYnwXZ",
49 "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",
50 "auth_config_id": "ac_aCYTppZ5RsRc",
51 "connected_account_id": "ca_cATYssZ5RrSc",
52 "trigger_id": "ti_JZFoTyYKbzhB",
53 "user_id": "pg-test-86c9fc84..."
54 },
55 "data": {
56 // Clean trigger data without Composio metadata
57 }
58 }
59 ```
60
61 ### Key Improvements
62
63 1. **Metadata Separation**: Composio-specific fields (connection IDs, trigger IDs, user IDs) are now in a dedicated `metadata` object
64 2. **Clean Data**: The `data` field now contains only the actual trigger payload without infrastructure metadata
65 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`
66 4. **Trigger Slug in Metadata**: The trigger slug (e.g., `GMAIL_NEW_GMAIL_MESSAGE`) is now available in `metadata.trigger_slug` for easy identification
67 5. **Standards Compliance**: Follows Standard Webhooks specification for better interoperability
68 6. **Consistent Structure**: Same payload structure for both webhooks and Pusher channels
69
70 ## Migration Guide
71
72 ### Updating Your Webhook Handlers
73
74 If you're accessing Composio metadata fields, update your code:
75
76 ```python
77 # Before (V2)
78 trigger_type = payload["type"] # "gmail_new_gmail_message"
79 connection_id = payload["data"]["connection_id"]
80 trigger_id = payload["data"]["trigger_id"]
81 message_text = payload["data"]["message_text"]
82
83 # After (V3)
84 trigger_type = payload["type"] # "composio.trigger.message"
85 trigger_slug = payload["metadata"]["trigger_slug"] # "GMAIL_NEW_GMAIL_MESSAGE"
86 connection_id = payload["metadata"]["connected_account_id"]
87 trigger_id = payload["metadata"]["trigger_id"]
88 message_text = payload["data"]["message_text"]
89 ```
90
91 ```typescript
92 // @noErrors
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 <Callout type="info">
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 </Callout>
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