Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 |