Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: restructure webhook and event notification guides
Sushmithamalleshb8f69170c345
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 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.jsonindex 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.mdxindex 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 triggersdescription: Receive trigger events via webhooks or SDK subscriptionskeywords: [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 eventsreturn {"status": "ok"}```@@ -73,11 +70,10 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiReif (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 locallydiff --git a/docs/content/docs/subscribing-to-connection-expiry-events.mdx b/docs/content/docs/subscribing-to-connection-expiry-events.mdxnew file mode 100644index 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.mdxindex 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 Establishmentdiff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdxindex 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.mdxsimilarity index 100%rename from docs/content/docs/setting-up-triggers/webhook-verification.mdxrename to docs/content/docs/webhook-verification.mdxdiff --git a/docs/next.config.mjs b/docs/next.config.mjsindex 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',