Skip to content

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

Sushmithamallesh4672a9cf3152
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
index 82084e1ae..1c5c2ff71 100644
--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx
+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
@@ -54,7 +54,7 @@ const userId = 'user-id-123435';
// Check what configuration is required
const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
console.log(triggerType.config);
-// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
+// Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
// Create trigger with the required config
const trigger = await composio.triggers.create(
diff --git a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
index 467908fd5..4ad032b59 100644
--- a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
@@ -6,91 +6,81 @@ keywords: [webhooks, subscribe, events, webhook payload, V3]
## Webhooks
-Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
-
-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)
-2. Build an endpoint that accepts POST requests with JSON payloads
-
-<Callout type="info">
-**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
-</Callout>
-
-Composio delivers two event types via webhooks:
+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:
| Event type | Description |
|------------|-------------|
-| `composio.trigger.message` | Trigger events from connected apps (all versions) |
-| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
-
-### Webhook payload (V3)
+| `composio.trigger.message` | Fired when a trigger receives data from an external service |
+| `composio.connected_account.expired` | Fired when a connected account expires and needs re-authentication |
+
+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):
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
+ -H "X-API-KEY: <your-composio-api-key>" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "webhook_url": "https://example.com/webhook",
+ "enabled_events": ["composio.trigger.message", "composio.connected_account.expired"]
+ }'
+```
-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:
+### Handling events
-```json
-{
- "id": "msg_abc123",
- "type": "composio.trigger.message",
- "metadata": {
- "log_id": "log_abc123",
- "trigger_slug": "GITHUB_COMMIT_EVENT",
- "trigger_id": "ti_xyz789",
- "connected_account_id": "ca_def456",
- "auth_config_id": "ac_xyz789",
- "user_id": "user-id-123435"
- },
- "data": {
- "commit_sha": "a1b2c3d",
- "message": "fix: resolve null pointer",
- "author": "jane"
- },
- "timestamp": "2026-01-15T10:30:00Z"
-}
-```
+All events arrive at the same endpoint. Route on the `type` field to handle each event type:
<Callout>
-See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
+[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.
</Callout>
-### Example handlers
-
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
+from composio import WebhookEventType
+
@app.post("/webhook")
async def webhook_handler(request: Request):
payload = await request.json()
+ event_type = payload.get("type")
+
+ if event_type == WebhookEventType.TRIGGER_MESSAGE:
+ trigger_slug = payload["metadata"]["trigger_slug"]
+ event_data = payload["data"]
- metadata = payload.get("metadata", {})
- trigger_slug = metadata.get("trigger_slug")
- event_data = payload.get("data", {})
+ if trigger_slug == "GITHUB_COMMIT_EVENT":
+ print(f"New commit by {event_data['author']}: {event_data['message']}")
- if trigger_slug == "GITHUB_COMMIT_EVENT":
- commit = event_data.get("message")
- author = event_data.get("author")
- print(f"New commit by {author}: {commit}")
+ elif event_type == WebhookEventType.CONNECTION_EXPIRED:
+ account_id = payload["data"]["id"]
+ toolkit = payload["data"]["toolkit"]["slug"]
+ print(f"Connection {account_id} expired for {toolkit}")
return {"status": "ok"}
```
</Tab>
<Tab value="TypeScript">
```typescript
-import { TriggerEvent } from '@composio/core';
+import { WebhookEventTypes, ConnectionExpiredEventSchema } from '@composio/core';
type NextApiRequest = { body: any };
-type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
-type GitHubCommitEventData = { commit_sha: string; message: string; author: string };
+type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
// ---cut---
export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
const payload = req.body;
- const triggerSlug = payload.metadata?.trigger_slug;
- if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
- const event: TriggerEvent<GitHubCommitEventData> = {
- type: payload.type,
- timestamp: payload.timestamp,
- data: payload.data
- };
-
- console.log(`New commit by ${event.data.author}: ${event.data.message}`);
+ if (payload.type === WebhookEventTypes.TRIGGER_MESSAGE) {
+ const triggerSlug = payload.metadata.trigger_slug;
+ const eventData = payload.data;
+
+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
+ console.log(`New commit by ${eventData.author}: ${eventData.message}`);
+ }
+ } else if (payload.type === WebhookEventTypes.CONNECTION_EXPIRED) {
+ const result = ConnectionExpiredEventSchema.safeParse(payload);
+ if (result.success) {
+ const { data } = result.data;
+ console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);
+ // Prompt user to re-authenticate
+ }
}
res.status(200).json({ status: 'ok' });
@@ -103,40 +93,66 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
</Callout>
-### Handling connection expiry events
+### Inspecting trigger payload schemas
-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:
+Each trigger type defines the schema of event data it sends. Use `get_type()`/`getType()` to inspect it before writing your handler:
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
-from composio import is_connection_expired_event
+from composio import Composio
-def handle_webhook(payload: dict):
- if is_connection_expired_event(payload):
- account_id = payload["data"]["id"]
- toolkit = payload["data"]["toolkit"]["slug"]
- print(f"Connection {account_id} expired for {toolkit}")
- # Prompt user to re-authenticate
+composio = Composio()
+
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
+print(trigger_type.payload)
+# Returns: {"properties": {"author": {...}, "id": {...}, "message": {...}, "timestamp": {...}, "url": {...}}}
```
</Tab>
<Tab value="TypeScript">
```typescript
-// @noErrors
-import { ConnectionExpiredEventSchema } from '@composio/core';
-// ---cut---
-function handleWebhook(payload: unknown) {
- const result = ConnectionExpiredEventSchema.safeParse(payload);
- if (result.success) {
- const { data, metadata } = result.data;
- console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);
- // Prompt user to re-authenticate
- }
-}
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
+console.log(triggerType.payload);
+// Returns: {"properties": {"author": {...}, "id": {...}, "message": {...}, "timestamp": {...}, "url": {...}}}
```
</Tab>
</Tabs>
+The payload schema tells you what fields will be in the `data` object of the webhook event.
+
+### Webhook payload (V3)
+
+New organizations receive V3 payloads by default. V3 separates event metadata from the actual event data:
+
+```json
+{
+ "id": "msg_abc123",
+ "type": "composio.trigger.message",
+ "metadata": {
+ "log_id": "log_abc123",
+ "trigger_slug": "GITHUB_COMMIT_EVENT",
+ "trigger_id": "ti_xyz789",
+ "connected_account_id": "ca_def456",
+ "auth_config_id": "ac_xyz789",
+ "user_id": "user-id-123435"
+ },
+ "data": {
+ "commit_sha": "a1b2c3d",
+ "message": "fix: resolve null pointer",
+ "author": "jane"
+ },
+ "timestamp": "2026-01-15T10:30:00Z"
+}
+```
+
+<Callout>
+See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
+</Callout>
+
## SDK subscriptions
For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.