Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: fix V3 payload format and add webhook subscriptions API references
- Fix V3 type field to "composio.trigger.message" with trigger_slug in metadata - Fix metadata fields to match actual API (snake_case, correct field set) - Update example handlers to route on metadata.trigger_slug - Add await to TS verifyWebhook() (async since SDK 0.6.0) - Add event types table (composio.trigger.message, composio.connected_account.expired) - Reference Webhook Subscriptions API in webhook setup steps - Add "Configure webhook endpoint" step to trigger lifecycle Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmithamallesh committed
Feb 9, 2026 at 15:52 UTC
c722b2947a548d8c0da5b4e7cd911ae0f17c1a83
3 files changed
+39
-21
docs/content/docs/setting-up-triggers/index.mdx
+21
-11
@@ -91,26 +91,34 @@ The trigger instance uses the toolkit version configured during Composio initial
91
92
Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
93
94
-1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
94
+1. Set your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/events) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks)
95
2. Build an endpoint that accepts POST requests with JSON payloads
96
97
<Callout type="info">
98
**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
99
</Callout>
100
101
+Composio delivers two event types via webhooks:
102
+
103
+| Event type | Description |
104
+|------------|-------------|
105
+| `composio.trigger.message` | Trigger events from connected apps (all versions) |
106
+| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
107
+
108
### Webhook payload (V3)
109
103
-New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
110
+New organizations receive V3 payloads by default. V3 uses a standardized `type` field (`composio.trigger.message`) and separates event metadata from the actual event data:
111
112
```json
113
{
107
- "id": "wh_abc123",
108
- "type": "github_commit_event",
114
+ "id": "msg_abc123",
115
+ "type": "composio.trigger.message",
116
"metadata": {
110
- "triggerId": "ti_xyz789",
111
- "connectedAccountId": "ca_def456",
112
- "userId": "user-id-123435",
113
- "toolkitSlug": "github"
117
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
118
+ "trigger_id": "ti_xyz789",
119
+ "connected_account_id": "ca_def456",
120
+ "auth_config_id": "ac_xyz789",
121
+ "user_id": "user-id-123435"
122
},
123
"data": {
124
"commit_sha": "a1b2c3d",
@@ -134,10 +142,11 @@ See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#we
142
async def webhook_handler(request: Request):
143
payload = await request.json()
144
137
- trigger_type = payload.get("type")
145
+ metadata = payload.get("metadata", {})
146
+ trigger_slug = metadata.get("trigger_slug")
147
event_data = payload.get("data", {})
148
140
- if trigger_type == "github_commit_event":
149
+ if trigger_slug == "GITHUB_COMMIT_EVENT":
150
commit = event_data.get("message")
151
author = event_data.get("author")
152
print(f"New commit by {author}: {commit}")
@@ -154,8 +163,9 @@ type GitHubCommitEventData = { commit_sha: string; message: string; author: stri
163
// ---cut---
164
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
165
const payload = req.body;
166
+ const triggerSlug = payload.metadata?.trigger_slug;
167
158
- if (payload.type === 'github_commit_event') {
168
+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
169
const event: TriggerEvent<GitHubCommitEventData> = {
170
type: payload.type,
171
timestamp: payload.timestamp,
docs/content/docs/setting-up-triggers/webhook-verification.mdx
+15
-8
@@ -46,9 +46,9 @@ type Response = { status: (code: number) => { json: (data: any) => void; send: (
46
// ---cut---
47
const composio = new Composio({ apiKey: 'your-api-key' });
48
49
-function handleWebhook(req: Request, res: Response) {
49
+async function handleWebhook(req: Request, res: Response) {
50
try {
51
- const result = composio.triggers.verifyWebhook({
51
+ const result = await composio.triggers.verifyWebhook({
52
payload: req.body,
53
signature: req.headers['webhook-signature'],
54
id: req.headers['webhook-id'],
@@ -158,13 +158,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
158
159
```json
160
{
161
- "id": "wh_abc123",
162
- "type": "github_commit_event",
161
+ "id": "msg_abc123",
162
+ "type": "composio.trigger.message",
163
"metadata": {
164
- "triggerId": "ti_xyz789",
165
- "connectedAccountId": "ca_def456",
166
- "userId": "user-id-123435",
167
- "toolkitSlug": "github"
164
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
165
+ "trigger_id": "ti_xyz789",
166
+ "connected_account_id": "ca_def456",
167
+ "auth_config_id": "ac_xyz789",
168
+ "user_id": "user-id-123435"
169
},
170
"data": {
171
"commit_sha": "a1b2c3d",
@@ -211,8 +212,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
212
213
## Configuring your webhook URL and secret
214
215
+You can configure webhooks via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks):
216
+
217
1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
218
2. Enter your publicly accessible webhook URL
219
3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
220
221
The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
222
+
223
+<Callout>
224
+The Webhook Subscriptions API also supports event filtering — subscribe only to `composio.trigger.message`, `composio.connected_account.expired`, or both. See the [API reference](/reference/api-reference/webhooks) for details.
225
+</Callout>
docs/content/docs/triggers.mdx
+3
-2
@@ -17,8 +17,9 @@ There are two delivery types:
17
18
1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
19
2. **Create** an active trigger scoped to a user's connected account
20
-3. **Receive events**: Composio delivers payloads to your webhook endpoint
21
-4. **Manage**: enable, disable, or delete triggers as needed
20
+3. **Configure** your webhook endpoint so Composio knows where to deliver events
21
+4. **Receive events**: Composio sends payloads to your endpoint
22
+5. **Manage**: enable, disable, or delete triggers as needed
23
24
<Accordions>
25
<Accordion title="What is a trigger type?">