@devries-cameron20 / composio Mirror · read-only / commits / b8f69170c
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 09:30 UTC

docs: restructure webhook and event notification guides

Separate webhook verification and connection expiry events from triggers into standalone guides, since they are distinct concepts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 11, 2026 at 12:58 UTC b8f69170c345d82a274e392fae2ec036ec40d602
8 files changed +179 -15
docs/content/docs/meta.json
+2
@@ -18,6 +18,8 @@
18 "white-labeling-authentication",
19 "managing-multiple-connected-accounts",
20 "using-custom-auth-configuration",
21 + "webhook-verification",
22 + "subscribing-to-connection-expiry-events",
23 "---Features---",
24 "cli",
25 "single-toolkit-mcp",
docs/content/docs/setting-up-triggers/meta.json
-1
@@ -3,7 +3,6 @@
3 "pages": [
4 "creating-triggers",
5 "subscribing-to-events",
6 - "webhook-verification",
6 "managing-triggers"
7 ]
8 }
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+8 -12
@@ -1,5 +1,5 @@
1 ---
2 -title: Subscribing to events
2 +title: Subscribing to triggers
3 description: Receive trigger events via webhooks or SDK subscriptions
4 keywords: [webhooks, subscribe, events, webhook payload, V3]
5 ---
@@ -11,7 +11,7 @@ Webhooks are the recommended way to receive trigger events in production. To sta
11 | Event type | Description |
12 |------------|-------------|
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 |
14 +| `composio.connected_account.expired` | Fired when a connected account expires and needs re-authentication. See [Subscribing to connection expiry events](/docs/subscribing-to-connection-expiry-events). |
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
@@ -21,7 +21,7 @@ curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
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"]
24 + "enabled_events": ["composio.trigger.message"]
25 }'
26 ```
27
@@ -50,10 +50,7 @@ async def webhook_handler(request: Request):
50 if trigger_slug == "GITHUB_COMMIT_EVENT":
51 print(f"New commit by {event_data['author']}: {event_data['message']}")
52
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}")
53 + # Handle connected account expired events
54
55 return {"status": "ok"}
56 ```
@@ -73,11 +70,10 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
70 if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
71 console.log(`New commit by ${eventData.author}: ${eventData.message}`);
72 }
76 - } else if (payload.type === 'composio.connected_account.expired') {
77 - console.log(`Connection ${payload.data.id} expired for ${payload.data.toolkit.slug}`);
78 - // Prompt user to re-authenticate
73 }
74
75 + // Handle connected account expired events
76 +
77 res.status(200).json({ status: 'ok' });
78 }
79 ```
@@ -85,7 +81,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
81 </Tabs>
82
83 <Callout type="warn">
88 -Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
84 +Always [verify webhook signatures](/docs/webhook-verification) in production to ensure payloads are authentic.
85 </Callout>
86
87 ### Inspecting trigger payload schemas
@@ -145,7 +141,7 @@ New organizations receive V3 payloads by default. V3 separates event metadata fr
141 ```
142
143 <Callout>
148 -See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
144 +See [webhook payload versions](/docs/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
145 </Callout>
146
147 ## Testing locally
docs/content/docs/subscribing-to-connection-expiry-events.mdx new
+162
@@ -0,0 +1,162 @@
1 +---
2 +title: Subscribing to connection expiry events
3 +description: Detect when OAuth connections expire and prompt users to re-authenticate
4 +keywords: [expired, connections, re-authenticate, webhook, oauth, refresh]
5 +---
6 +
7 +Composio automatically refreshes OAuth tokens before they expire. But when a refresh token is revoked or expires, the connection enters an `EXPIRED` state and the user must re-authenticate.
8 +
9 +You can detect this proactively using the `composio.connected_account.expired` webhook event instead of waiting for a tool execution to fail.
10 +
11 +<Callout>
12 +This event is only available with [V3 webhook payloads](/docs/webhook-verification#webhook-payload-versions). New organizations use V3 by default.
13 +</Callout>
14 +
15 +## Subscribe to expiry events
16 +
17 +Add `composio.connected_account.expired` to your webhook subscription's `enabled_events`:
18 +
19 +```bash
20 +curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
21 + -H "X-API-KEY: <your-composio-api-key>" \
22 + -H "Content-Type: application/json" \
23 + -d '{
24 + "webhook_url": "https://example.com/webhook",
25 + "enabled_events": [
26 + "composio.trigger.message",
27 + "composio.connected_account.expired"
28 + ]
29 + }'
30 +```
31 +
32 +## Handle the event
33 +
34 +When a connection expires, Composio sends a webhook with the connected account details:
35 +
36 +```json
37 +{
38 + "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
39 + "type": "composio.connected_account.expired",
40 + "metadata": {
41 + "project_id": "pr_your-project-id",
42 + "org_id": "ok_your-org-id"
43 + },
44 + "data": {
45 + "id": "ca_your-connected-account-id",
46 + "toolkit": { "slug": "gmail" },
47 + "auth_config": {
48 + "id": "ac_your-auth-config-id",
49 + "auth_scheme": "OAUTH2"
50 + },
51 + "status": "EXPIRED",
52 + "status_reason": "OAuth refresh token expired"
53 + },
54 + "timestamp": "2026-02-06T12:00:00.000Z"
55 +}
56 +```
57 +
58 +Route on `type` to handle expiry alongside trigger events:
59 +
60 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
61 + <Tab value="Python">
62 +```python
63 +from composio import Composio, WebhookEventType
64 +
65 +composio = Composio()
66 +
67 +@app.post("/webhook")
68 +async def webhook_handler(request: Request):
69 + payload = await request.json()
70 + event_type = payload.get("type")
71 +
72 + if event_type == WebhookEventType.CONNECTION_EXPIRED:
73 + account_id = payload["data"]["id"]
74 + toolkit = payload["data"]["toolkit"]["slug"]
75 +
76 + # Look up the user and send them a re-auth link
77 + session = composio.create(user_id=lookup_user(account_id))
78 + connection_request = session.authorize(toolkit)
79 + notify_user(connection_request.redirect_url)
80 +
81 + elif event_type == WebhookEventType.TRIGGER_MESSAGE:
82 + # Handle trigger events
83 + pass
84 +
85 + return {"status": "ok"}
86 +```
87 + </Tab>
88 + <Tab value="TypeScript">
89 +```typescript
90 +import { Composio } from '@composio/core';
91 +const composio = new Composio();
92 +type NextApiRequest = { body: any };
93 +type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
94 +declare function lookupUser(accountId: string): string;
95 +declare function notifyUser(url: string): void;
96 +// ---cut---
97 +export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
98 + const payload = req.body;
99 +
100 + if (payload.type === 'composio.connected_account.expired') {
101 + const accountId = payload.data.id;
102 + const toolkit = payload.data.toolkit.slug;
103 +
104 + // Look up the user and send them a re-auth link
105 + const session = await composio.create(lookupUser(accountId));
106 + const connectionRequest = await session.authorize(toolkit);
107 + notifyUser(connectionRequest.redirectUrl);
108 +
109 + } else if (payload.type === 'composio.trigger.message') {
110 + // Handle trigger events
111 + }
112 +
113 + res.status(200).json({ status: 'ok' });
114 +}
115 +```
116 + </Tab>
117 +</Tabs>
118 +
119 +## Re-authenticate the user
120 +
121 +Use `session.authorize()` to generate a new Connect Link for the expired toolkit. The user completes OAuth again, and the connected account returns to `ACTIVE` status.
122 +
123 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
124 + <Tab value="Python">
125 +```python
126 +from composio import Composio
127 +
128 +composio = Composio()
129 +
130 +session = composio.create(user_id="user_123")
131 +connection_request = session.authorize("gmail")
132 +
133 +# Send this URL to the user (email, in-app notification, etc.)
134 +print(connection_request.redirect_url)
135 +
136 +# Optionally wait for completion
137 +connected_account = connection_request.wait_for_connection(60000)
138 +print(f"Re-connected: {connected_account.id}")
139 +```
140 + </Tab>
141 + <Tab value="TypeScript">
142 +```typescript
143 +import { Composio } from '@composio/core';
144 +
145 +const composio = new Composio();
146 +
147 +const session = await composio.create("user_123");
148 +const connectionRequest = await session.authorize("gmail");
149 +
150 +// Send this URL to the user (email, in-app notification, etc.)
151 +console.log(connectionRequest.redirectUrl);
152 +
153 +// Optionally wait for completion
154 +const connectedAccount = await connectionRequest.waitForConnection(60000);
155 +console.log(`Re-connected: ${connectedAccount.id}`);
156 +```
157 + </Tab>
158 +</Tabs>
159 +
160 +<Callout>
161 +Always [verify webhook signatures](/docs/webhook-verification) before processing events in production.
162 +</Callout>
docs/content/docs/tools-direct/authenticating-tools.mdx
+1 -1
@@ -397,7 +397,7 @@ After creating a connection, it will have one of the following statuses that ind
397 | **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |
398
399 <Callout>
400 -When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed.
400 +When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed. Set up [connection expiry event notifications](/docs/subscribing-to-connection-expiry-events) to detect this proactively.
401 </Callout>
402
403 ### Waiting for Connection Establishment
docs/content/docs/triggers.mdx
+1 -1
@@ -35,6 +35,6 @@ When you create a trigger from a type, it's scoped to a specific user and connec
35 <Cards>
36 <Card title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />
37 <Card title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
38 - <Card title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
38 + <Card title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
39 <Card title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
40 </Cards>
docs/content/docs/webhook-verification.mdx renamed
docs/next.config.mjs
+5
@@ -210,6 +210,11 @@ const config = {
210 destination: '/docs/setting-up-triggers/creating-triggers',
211 permanent: true,
212 },
213 + {
214 + source: '/docs/setting-up-triggers/webhook-verification',
215 + destination: '/docs/webhook-verification',
216 + permanent: true,
217 + },
218 {
219 source: '/triggers',
220 destination: '/docs/triggers',