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',