@devries-cameron20 / composio Mirror · read-only
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 21, 03:37 UTC

next
mdx 165 lines 6.42 KB
Raw
1 Webhook subscriptions are outbound delivery configurations. They define the URL Composio posts [trigger](/docs/triggers) events to, along with the signing secret and the set of event types you want to receive.
2
3 Reach for these endpoints to register where Composio should send events, to filter delivery to specific event types, and to manage the signing secret used to verify those deliveries. List the available event types with the `/webhook_subscriptions/event_types` endpoint, then create a subscription scoped to the ones you care about.
4
5 Each subscription is addressed by its `id`. You can update its URL and filters with `PATCH`, delete it, and rotate its signing secret with `/webhook_subscriptions/{id}/rotate_secret` if the secret leaks.
6
7 Every webhook request Composio sends includes `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Store the secret as `COMPOSIO_WEBHOOK_SECRET` and verify each payload before trusting it. See [Verifying signatures](/docs/setting-up-triggers/subscribing-to-events#verifying-signatures) for the SDK and manual verification flows.
8
9 ## Event types
10
11 A subscription's `enabled_events` controls which events get delivered to its URL. Two broad families exist:
12
13 - **Trigger events** like `composio.trigger.message` — payloads emitted by [triggers](/docs/triggers) you've enabled (new email, new issue, etc.).
14 - **Lifecycle events** like `composio.connected_account.expired` — emitted when a [connected account](/docs/auth-configuration/connected-accounts) changes state.
15
16 List everything you can subscribe to with the `/webhook_subscriptions/event_types` endpoint, then scope a subscription to the events you handle.
17
18 ## Detecting connection expiry
19
20 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.
21
22 Subscribe to the `composio.connected_account.expired` event to detect this proactively, instead of waiting for a tool execution to fail.
23
24 <Callout>
25 This event is only available with [V3 webhook payloads](/docs/setting-up-triggers/subscribing-to-events#webhook-payload-versions). New organizations use V3 by default.
26 </Callout>
27
28 Update your existing subscription to deliver both trigger messages and connection-expiry events. Replace `whs_123` with the ID from [List webhook subscriptions](/reference/api-reference/webhook-subscriptions/getWebhookSubscriptions). Include any other events you want to keep in `enabled_events`.
29
30 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
31 <Tab value="Python">
32 ```python
33 from composio import Composio
34
35 composio = Composio()
36
37 subscription = composio.webhooks.subscriptions.update(
38 "whs_123",
39 webhook_url="https://example.com/webhook",
40 enabled_events=[
41 "composio.trigger.message",
42 "composio.connected_account.expired",
43 ],
44 )
45 ```
46 </Tab>
47 <Tab value="TypeScript">
48 ```typescript
49 import { Composio } from '@composio/core';
50
51 const composio = new Composio();
52
53 const subscription = await composio.webhooks.subscriptions.update('whs_123', {
54 webhookUrl: 'https://example.com/webhook',
55 enabledEvents: ['composio.trigger.message', 'composio.connected_account.expired'],
56 });
57 ```
58 </Tab>
59 <Tab value="API">
60 ```bash
61 curl -X PATCH https://backend.composio.dev/api/v3.1/webhook_subscriptions/whs_123 \
62 -H "x-api-key: $COMPOSIO_API_KEY" \
63 -H "Content-Type: application/json" \
64 -d '{
65 "webhook_url": "https://example.com/webhook",
66 "enabled_events": [
67 "composio.trigger.message",
68 "composio.connected_account.expired"
69 ]
70 }'
71 ```
72 </Tab>
73 </Tabs>
74
75 When a connection expires, Composio sends a webhook with the connected account details:
76
77 ```json
78 {
79 "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
80 "type": "composio.connected_account.expired",
81 "metadata": {
82 "project_id": "pr_your-project-id",
83 "org_id": "ok_your-org-id"
84 },
85 "data": {
86 "id": "ca_your-connected-account-id",
87 "toolkit": { "slug": "gmail" },
88 "auth_config": {
89 "id": "ac_your-auth-config-id",
90 "auth_scheme": "OAUTH2"
91 },
92 "status": "EXPIRED",
93 "status_reason": "OAuth refresh token expired"
94 },
95 "timestamp": "2026-02-06T12:00:00.000Z"
96 }
97 ```
98
99 Route on `type` to handle expiry alongside trigger events:
100
101 {/* code-example: no-api reason="webhook receiver framework code verifies incoming requests locally; the session and link API operations are shown in the authentication guide" */}
102 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
103 <Tab value="Python">
104 ```python
105 from composio import Composio, WebhookEventType
106
107 composio = Composio()
108
109 @app.post("/webhook")
110 async def webhook_handler(request: Request):
111 payload = await request.json()
112 event_type = payload.get("type")
113
114 if event_type == WebhookEventType.CONNECTION_EXPIRED:
115 account_id = payload["data"]["id"]
116 toolkit = payload["data"]["toolkit"]["slug"]
117
118 # Look up the user and send them a re-auth link
119 session = composio.create(user_id=lookup_user(account_id))
120 connection_request = session.authorize(toolkit)
121 notify_user(connection_request.redirect_url)
122
123 elif event_type == WebhookEventType.TRIGGER_MESSAGE:
124 # Handle trigger events
125 pass
126
127 return {"status": "ok"}
128 ```
129 </Tab>
130 <Tab value="TypeScript">
131 ```typescript
132 import { Composio } from '@composio/core';
133 const composio = new Composio();
134 type NextApiRequest = { body: any };
135 type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
136 declare function lookupUser(accountId: string): string;
137 declare function notifyUser(url: string): void;
138 // ---cut---
139 export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
140 const payload = req.body;
141
142 if (payload.type === 'composio.connected_account.expired') {
143 const accountId = payload.data.id;
144 const toolkit = payload.data.toolkit.slug;
145
146 // Look up the user and send them a re-auth link
147 const session = await composio.create(lookupUser(accountId));
148 const connectionRequest = await session.authorize(toolkit);
149 if (connectionRequest.redirectUrl) {
150 notifyUser(connectionRequest.redirectUrl);
151 }
152
153 } else if (payload.type === 'composio.trigger.message') {
154 // Handle trigger events
155 }
156
157 res.status(200).json({ status: 'ok' });
158 }
159 ```
160 </Tab>
161 </Tabs>
162
163 <Callout>
164 Always [verify webhook signatures](/docs/setting-up-triggers/subscribing-to-events#verifying-signatures) before processing events in production.
165 </Callout>