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: revamp subscribing-to-events with unified handler, payload schemas, SDK enums
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmithamallesh committed
Feb 10, 2026 at 06:58 UTC
4672a9cf315284b7f514b35a36eecf3889160eab
2 files changed
+94
-78
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1
-1
@@ -54,7 +54,7 @@ const userId = 'user-id-123435';
54
// Check what configuration is required
55
const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
56
console.log(triggerType.config);
57
-// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
57
+// Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
58
59
// Create trigger with the required config
60
const trigger = await composio.triggers.create(
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+93
-77
@@ -6,91 +6,81 @@ keywords: [webhooks, subscribe, events, webhook payload, V3]
6
7
## Webhooks
8
9
-Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
10
-
11
-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)
12
-2. Build an endpoint that accepts POST requests with JSON payloads
13
-
14
-<Callout type="info">
15
-**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
16
-</Callout>
17
-
18
-Composio delivers two event types via webhooks:
9
+Webhooks are the recommended way to receive trigger events in production. To start receiving events, create a webhook subscription with your endpoint URL and select which event types you want to receive. You can subscribe to one or both:
10
11
| Event type | Description |
12
|------------|-------------|
22
-| `composio.trigger.message` | Trigger events from connected apps (all versions) |
23
-| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
24
-
25
-### Webhook payload (V3)
13
+| `composio.trigger.message` | Fired when a trigger receives data from an external service |
14
+| `composio.connected_account.expired` | Fired when a connected account expires and needs re-authentication |
15
+
16
+Set your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/webhook) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks):
17
+
18
+```bash
19
+curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
20
+ -H "X-API-KEY: <your-composio-api-key>" \
21
+ -H "Content-Type: application/json" \
22
+ -d '{
23
+ "webhook_url": "https://example.com/webhook",
24
+ "enabled_events": ["composio.trigger.message", "composio.connected_account.expired"]
25
+ }'
26
+```
27
27
-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:
28
+### Handling events
29
29
-```json
30
-{
31
- "id": "msg_abc123",
32
- "type": "composio.trigger.message",
33
- "metadata": {
34
- "log_id": "log_abc123",
35
- "trigger_slug": "GITHUB_COMMIT_EVENT",
36
- "trigger_id": "ti_xyz789",
37
- "connected_account_id": "ca_def456",
38
- "auth_config_id": "ac_xyz789",
39
- "user_id": "user-id-123435"
40
- },
41
- "data": {
42
- "commit_sha": "a1b2c3d",
43
- "message": "fix: resolve null pointer",
44
- "author": "jane"
45
- },
46
- "timestamp": "2026-01-15T10:30:00Z"
47
-}
48
-```
30
+All events arrive at the same endpoint. Route on the `type` field to handle each event type:
31
32
<Callout>
51
-See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
33
+[Inspect the payload schema](#inspecting-trigger-payload-schemas) for a trigger before writing your handler. See [Webhook payload (V3)](#webhook-payload-v3) for the full event structure.
34
</Callout>
35
54
-### Example handlers
55
-
36
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
37
<Tab value="Python">
38
```python
39
+from composio import WebhookEventType
40
+
41
@app.post("/webhook")
42
async def webhook_handler(request: Request):
43
payload = await request.json()
44
+ event_type = payload.get("type")
45
+
46
+ if event_type == WebhookEventType.TRIGGER_MESSAGE:
47
+ trigger_slug = payload["metadata"]["trigger_slug"]
48
+ event_data = payload["data"]
49
63
- metadata = payload.get("metadata", {})
64
- trigger_slug = metadata.get("trigger_slug")
65
- event_data = payload.get("data", {})
50
+ if trigger_slug == "GITHUB_COMMIT_EVENT":
51
+ print(f"New commit by {event_data['author']}: {event_data['message']}")
52
67
- if trigger_slug == "GITHUB_COMMIT_EVENT":
68
- commit = event_data.get("message")
69
- author = event_data.get("author")
70
- print(f"New commit by {author}: {commit}")
53
+ elif event_type == WebhookEventType.CONNECTION_EXPIRED:
54
+ account_id = payload["data"]["id"]
55
+ toolkit = payload["data"]["toolkit"]["slug"]
56
+ print(f"Connection {account_id} expired for {toolkit}")
57
58
return {"status": "ok"}
59
```
60
</Tab>
61
<Tab value="TypeScript">
62
```typescript
77
-import { TriggerEvent } from '@composio/core';
63
+import { WebhookEventTypes, ConnectionExpiredEventSchema } from '@composio/core';
64
type NextApiRequest = { body: any };
79
-type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
80
-type GitHubCommitEventData = { commit_sha: string; message: string; author: string };
65
+type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
66
// ---cut---
67
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
68
const payload = req.body;
84
- const triggerSlug = payload.metadata?.trigger_slug;
69
86
- if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
87
- const event: TriggerEvent<GitHubCommitEventData> = {
88
- type: payload.type,
89
- timestamp: payload.timestamp,
90
- data: payload.data
91
- };
92
-
93
- console.log(`New commit by ${event.data.author}: ${event.data.message}`);
70
+ if (payload.type === WebhookEventTypes.TRIGGER_MESSAGE) {
71
+ const triggerSlug = payload.metadata.trigger_slug;
72
+ const eventData = payload.data;
73
+
74
+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
75
+ console.log(`New commit by ${eventData.author}: ${eventData.message}`);
76
+ }
77
+ } else if (payload.type === WebhookEventTypes.CONNECTION_EXPIRED) {
78
+ const result = ConnectionExpiredEventSchema.safeParse(payload);
79
+ if (result.success) {
80
+ const { data } = result.data;
81
+ console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);
82
+ // Prompt user to re-authenticate
83
+ }
84
}
85
86
res.status(200).json({ status: 'ok' });
@@ -103,40 +93,66 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
93
Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
94
</Callout>
95
106
-### Handling connection expiry events
96
+### Inspecting trigger payload schemas
97
108
-If you subscribe to `composio.connected_account.expired` events via the [Webhook Subscriptions API](/reference/api-reference/webhooks), Composio notifies you when an OAuth2 connection expires. The SDK provides typed schemas for these events:
98
+Each trigger type defines the schema of event data it sends. Use `get_type()`/`getType()` to inspect it before writing your handler:
99
100
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
101
<Tab value="Python">
102
```python
113
-from composio import is_connection_expired_event
103
+from composio import Composio
104
115
-def handle_webhook(payload: dict):
116
- if is_connection_expired_event(payload):
117
- account_id = payload["data"]["id"]
118
- toolkit = payload["data"]["toolkit"]["slug"]
119
- print(f"Connection {account_id} expired for {toolkit}")
120
- # Prompt user to re-authenticate
105
+composio = Composio()
106
+
107
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
108
+print(trigger_type.payload)
109
+# Returns: {"properties": {"author": {...}, "id": {...}, "message": {...}, "timestamp": {...}, "url": {...}}}
110
```
111
</Tab>
112
<Tab value="TypeScript">
113
```typescript
125
-// @noErrors
126
-import { ConnectionExpiredEventSchema } from '@composio/core';
127
-// ---cut---
128
-function handleWebhook(payload: unknown) {
129
- const result = ConnectionExpiredEventSchema.safeParse(payload);
130
- if (result.success) {
131
- const { data, metadata } = result.data;
132
- console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);
133
- // Prompt user to re-authenticate
134
- }
135
-}
114
+import { Composio } from '@composio/core';
115
+
116
+const composio = new Composio();
117
+
118
+const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
119
+console.log(triggerType.payload);
120
+// Returns: {"properties": {"author": {...}, "id": {...}, "message": {...}, "timestamp": {...}, "url": {...}}}
121
```
122
</Tab>
123
</Tabs>
124
125
+The payload schema tells you what fields will be in the `data` object of the webhook event.
126
+
127
+### Webhook payload (V3)
128
+
129
+New organizations receive V3 payloads by default. V3 separates event metadata from the actual event data:
130
+
131
+```json
132
+{
133
+ "id": "msg_abc123",
134
+ "type": "composio.trigger.message",
135
+ "metadata": {
136
+ "log_id": "log_abc123",
137
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
138
+ "trigger_id": "ti_xyz789",
139
+ "connected_account_id": "ca_def456",
140
+ "auth_config_id": "ac_xyz789",
141
+ "user_id": "user-id-123435"
142
+ },
143
+ "data": {
144
+ "commit_sha": "a1b2c3d",
145
+ "message": "fix: resolve null pointer",
146
+ "author": "jane"
147
+ },
148
+ "timestamp": "2026-01-15T10:30:00Z"
149
+}
150
+```
151
+
152
+<Callout>
153
+See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
154
+</Callout>
155
+
156
## SDK subscriptions
157
158
For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.