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: restructure webhook and event notification guides

Sushmithamalleshb8f69170c345
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index f1f56f093..e35b2fcce 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -18,6 +18,8 @@
"white-labeling-authentication",
"managing-multiple-connected-accounts",
"using-custom-auth-configuration",
+ "webhook-verification",
+ "subscribing-to-connection-expiry-events",
"---Features---",
"cli",
"single-toolkit-mcp",
diff --git a/docs/content/docs/setting-up-triggers/meta.json b/docs/content/docs/setting-up-triggers/meta.json
index a55218239..b08a63928 100644
--- a/docs/content/docs/setting-up-triggers/meta.json
+++ b/docs/content/docs/setting-up-triggers/meta.json
@@ -3,7 +3,6 @@
"pages": [
"creating-triggers",
"subscribing-to-events",
- "webhook-verification",
"managing-triggers"
]
}
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 a19bcca13..cfd4ebc4f 100644
--- a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
@@ -1,5 +1,5 @@
---
-title: Subscribing to events
+title: Subscribing to triggers
description: Receive trigger events via webhooks or SDK subscriptions
keywords: [webhooks, subscribe, events, webhook payload, V3]
---
@@ -11,7 +11,7 @@ Webhooks are the recommended way to receive trigger events in production. To sta
| Event type | Description |
|------------|-------------|
| `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 |
+| `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). |
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):
@@ -21,7 +21,7 @@ curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://example.com/webhook",
- "enabled_events": ["composio.trigger.message", "composio.connected_account.expired"]
+ "enabled_events": ["composio.trigger.message"]
}'
```
@@ -50,10 +50,7 @@ async def webhook_handler(request: Request):
if trigger_slug == "GITHUB_COMMIT_EVENT":
print(f"New commit by {event_data['author']}: {event_data['message']}")
- elif event_type == WebhookEventType.CONNECTION_EXPIRED:
- account_id = payload["data"]["id"]
- toolkit = payload["data"]["toolkit"]["slug"]
- print(f"Connection {account_id} expired for {toolkit}")
+ # Handle connected account expired events
return {"status": "ok"}
```
@@ -73,11 +70,10 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
console.log(`New commit by ${eventData.author}: ${eventData.message}`);
}
- } else if (payload.type === 'composio.connected_account.expired') {
- console.log(`Connection ${payload.data.id} expired for ${payload.data.toolkit.slug}`);
- // Prompt user to re-authenticate
}
+ // Handle connected account expired events
+
res.status(200).json({ status: 'ok' });
}
```
@@ -85,7 +81,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
</Tabs>
<Callout type="warn">
-Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
+Always [verify webhook signatures](/docs/webhook-verification) in production to ensure payloads are authentic.
</Callout>
### Inspecting trigger payload schemas
@@ -145,7 +141,7 @@ New organizations receive V3 payloads by default. V3 separates event metadata fr
```
<Callout>
-See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
+See [webhook payload versions](/docs/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
</Callout>
## Testing locally
diff --git a/docs/content/docs/subscribing-to-connection-expiry-events.mdx b/docs/content/docs/subscribing-to-connection-expiry-events.mdx
new file mode 100644
index 000000000..c4e38ac6c
--- /dev/null
+++ b/docs/content/docs/subscribing-to-connection-expiry-events.mdx
@@ -0,0 +1,162 @@
+---
+title: Subscribing to connection expiry events
+description: Detect when OAuth connections expire and prompt users to re-authenticate
+keywords: [expired, connections, re-authenticate, webhook, oauth, refresh]
+---
+
+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.
+
+You can detect this proactively using the `composio.connected_account.expired` webhook event instead of waiting for a tool execution to fail.
+
+<Callout>
+This event is only available with [V3 webhook payloads](/docs/webhook-verification#webhook-payload-versions). New organizations use V3 by default.
+</Callout>
+
+## Subscribe to expiry events
+
+Add `composio.connected_account.expired` to your webhook subscription's `enabled_events`:
+
+```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"
+ ]
+ }'
+```
+
+## Handle the event
+
+When a connection expires, Composio sends a webhook with the connected account details:
+
+```json
+{
+ "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
+ "type": "composio.connected_account.expired",
+ "metadata": {
+ "project_id": "pr_your-project-id",
+ "org_id": "ok_your-org-id"
+ },
+ "data": {
+ "id": "ca_your-connected-account-id",
+ "toolkit": { "slug": "gmail" },
+ "auth_config": {
+ "id": "ac_your-auth-config-id",
+ "auth_scheme": "OAUTH2"
+ },
+ "status": "EXPIRED",
+ "status_reason": "OAuth refresh token expired"
+ },
+ "timestamp": "2026-02-06T12:00:00.000Z"
+}
+```
+
+Route on `type` to handle expiry alongside trigger events:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio, WebhookEventType
+
+composio = Composio()
+
[email protected]("/webhook")
+async def webhook_handler(request: Request):
+ payload = await request.json()
+ event_type = payload.get("type")
+
+ if event_type == WebhookEventType.CONNECTION_EXPIRED:
+ account_id = payload["data"]["id"]
+ toolkit = payload["data"]["toolkit"]["slug"]
+
+ # Look up the user and send them a re-auth link
+ session = composio.create(user_id=lookup_user(account_id))
+ connection_request = session.authorize(toolkit)
+ notify_user(connection_request.redirect_url)
+
+ elif event_type == WebhookEventType.TRIGGER_MESSAGE:
+ # Handle trigger events
+ pass
+
+ return {"status": "ok"}
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio();
+type NextApiRequest = { body: any };
+type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
+declare function lookupUser(accountId: string): string;
+declare function notifyUser(url: string): void;
+// ---cut---
+export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
+ const payload = req.body;
+
+ if (payload.type === 'composio.connected_account.expired') {
+ const accountId = payload.data.id;
+ const toolkit = payload.data.toolkit.slug;
+
+ // Look up the user and send them a re-auth link
+ const session = await composio.create(lookupUser(accountId));
+ const connectionRequest = await session.authorize(toolkit);
+ notifyUser(connectionRequest.redirectUrl);
+
+ } else if (payload.type === 'composio.trigger.message') {
+ // Handle trigger events
+ }
+
+ res.status(200).json({ status: 'ok' });
+}
+```
+ </Tab>
+</Tabs>
+
+## Re-authenticate the user
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio()
+
+session = composio.create(user_id="user_123")
+connection_request = session.authorize("gmail")
+
+# Send this URL to the user (email, in-app notification, etc.)
+print(connection_request.redirect_url)
+
+# Optionally wait for completion
+connected_account = connection_request.wait_for_connection(60000)
+print(f"Re-connected: {connected_account.id}")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+const session = await composio.create("user_123");
+const connectionRequest = await session.authorize("gmail");
+
+// Send this URL to the user (email, in-app notification, etc.)
+console.log(connectionRequest.redirectUrl);
+
+// Optionally wait for completion
+const connectedAccount = await connectionRequest.waitForConnection(60000);
+console.log(`Re-connected: ${connectedAccount.id}`);
+```
+ </Tab>
+</Tabs>
+
+<Callout>
+Always [verify webhook signatures](/docs/webhook-verification) before processing events in production.
+</Callout>
diff --git a/docs/content/docs/tools-direct/authenticating-tools.mdx b/docs/content/docs/tools-direct/authenticating-tools.mdx
index 44180dac8..6e2b8f473 100644
--- a/docs/content/docs/tools-direct/authenticating-tools.mdx
+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx
@@ -397,7 +397,7 @@ After creating a connection, it will have one of the following statuses that ind
| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |
<Callout>
-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.
+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.
</Callout>
### Waiting for Connection Establishment
diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdx
index 96ffdc8d1..839d32555 100644
--- a/docs/content/docs/triggers.mdx
+++ b/docs/content/docs/triggers.mdx
@@ -35,6 +35,6 @@ When you create a trigger from a type, it's scoped to a specific user and connec
<Cards>
<Card title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />
<Card title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
- <Card title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
+ <Card title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
<Card title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
</Cards>
diff --git a/docs/content/docs/setting-up-triggers/webhook-verification.mdx b/docs/content/docs/webhook-verification.mdx
similarity index 100%
rename from docs/content/docs/setting-up-triggers/webhook-verification.mdx
rename to docs/content/docs/webhook-verification.mdx
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 1e97a430f..6f5c7614c 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -210,6 +210,11 @@ const config = {
destination: '/docs/setting-up-triggers/creating-triggers',
permanent: true,
},
+ {
+ source: '/docs/setting-up-triggers/webhook-verification',
+ destination: '/docs/webhook-verification',
+ permanent: true,
+ },
{
source: '/triggers',
destination: '/docs/triggers',