@devries-cameron20 / composio-1 / commits / 4672a9cf3
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.

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.