@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, 04:45 UTC

next
mdx 176 lines 8.44 KB
Raw
1 ---
2 title: Webhook Subscriptions
3 description: "Webhook delivery subscriptions. Outbound URLs Composio posts trigger events to, plus signing secret rotation and event-type filters."
4 ---
5
6 {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/webhook-subscriptions.mdx, not this file. */}
7
8 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.
9
10 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.
11
12 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.
13
14 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.
15
16 ## Event types
17
18 A subscription's `enabled_events` controls which events get delivered to its URL. Two broad families exist:
19
20 - **Trigger events** like `composio.trigger.message` — payloads emitted by [triggers](/docs/triggers) you've enabled (new email, new issue, etc.).
21 - **Lifecycle events** like `composio.connected_account.expired` — emitted when a [connected account](/docs/auth-configuration/connected-accounts) changes state.
22
23 List everything you can subscribe to with the `/webhook_subscriptions/event_types` endpoint, then scope a subscription to the events you handle.
24
25 ## Detecting connection expiry
26
27 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.
28
29 Subscribe to the `composio.connected_account.expired` event to detect this proactively, instead of waiting for a tool execution to fail.
30
31 <Callout>
32 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.
33 </Callout>
34
35 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`.
36
37 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
38 <Tab value="Python">
39 ```python
40 from composio import Composio
41
42 composio = Composio()
43
44 subscription = composio.webhooks.subscriptions.update(
45 "whs_123",
46 webhook_url="https://example.com/webhook",
47 enabled_events=[
48 "composio.trigger.message",
49 "composio.connected_account.expired",
50 ],
51 )
52 ```
53 </Tab>
54 <Tab value="TypeScript">
55 ```typescript
56 import { Composio } from '@composio/core';
57
58 const composio = new Composio();
59
60 const subscription = await composio.webhooks.subscriptions.update('whs_123', {
61 webhookUrl: 'https://example.com/webhook',
62 enabledEvents: ['composio.trigger.message', 'composio.connected_account.expired'],
63 });
64 ```
65 </Tab>
66 <Tab value="API">
67 ```bash
68 curl -X PATCH https://backend.composio.dev/api/v3.1/webhook_subscriptions/whs_123 \
69 -H "x-api-key: $COMPOSIO_API_KEY" \
70 -H "Content-Type: application/json" \
71 -d '{
72 "webhook_url": "https://example.com/webhook",
73 "enabled_events": [
74 "composio.trigger.message",
75 "composio.connected_account.expired"
76 ]
77 }'
78 ```
79 </Tab>
80 </Tabs>
81
82 When a connection expires, Composio sends a webhook with the connected account details:
83
84 ```json
85 {
86 "id": "evt_847cdfcd-d219-4f18-a6dd-91acd42ca94a",
87 "type": "composio.connected_account.expired",
88 "metadata": {
89 "project_id": "pr_your-project-id",
90 "org_id": "ok_your-org-id"
91 },
92 "data": {
93 "id": "ca_your-connected-account-id",
94 "toolkit": { "slug": "gmail" },
95 "auth_config": {
96 "id": "ac_your-auth-config-id",
97 "auth_scheme": "OAUTH2"
98 },
99 "status": "EXPIRED",
100 "status_reason": "OAuth refresh token expired"
101 },
102 "timestamp": "2026-02-06T12:00:00.000Z"
103 }
104 ```
105
106 Route on `type` to handle expiry alongside trigger events:
107
108 {/* 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" */}
109 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
110 <Tab value="Python">
111 ```python
112 from composio import Composio, WebhookEventType
113
114 composio = Composio()
115
116 @app.post("/webhook")
117 async def webhook_handler(request: Request):
118 payload = await request.json()
119 event_type = payload.get("type")
120
121 if event_type == WebhookEventType.CONNECTION_EXPIRED:
122 account_id = payload["data"]["id"]
123 toolkit = payload["data"]["toolkit"]["slug"]
124
125 # Look up the user and send them a re-auth link
126 session = composio.create(user_id=lookup_user(account_id))
127 connection_request = session.authorize(toolkit)
128 notify_user(connection_request.redirect_url)
129
130 elif event_type == WebhookEventType.TRIGGER_MESSAGE:
131 # Handle trigger events
132 pass
133
134 return {"status": "ok"}
135 ```
136 </Tab>
137 <Tab value="TypeScript">
138 ```typescript
139 import { Composio } from '@composio/core';
140 const composio = new Composio();
141 type NextApiRequest = { body: any };
142 type NextApiResponse = { status: (code: number) => { json: (data: any) => void } };
143 declare function lookupUser(accountId: string): string;
144 declare function notifyUser(url: string): void;
145 // ---cut---
146 export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
147 const payload = req.body;
148
149 if (payload.type === 'composio.connected_account.expired') {
150 const accountId = payload.data.id;
151 const toolkit = payload.data.toolkit.slug;
152
153 // Look up the user and send them a re-auth link
154 const session = await composio.create(lookupUser(accountId));
155 const connectionRequest = await session.authorize(toolkit);
156 if (connectionRequest.redirectUrl) {
157 notifyUser(connectionRequest.redirectUrl);
158 }
159
160 } else if (payload.type === 'composio.trigger.message') {
161 // Handle trigger events
162 }
163
164 res.status(200).json({ status: 'ok' });
165 }
166 ```
167 </Tab>
168 </Tabs>
169
170 <Callout>
171 Always [verify webhook signatures](/docs/setting-up-triggers/subscribing-to-events#verifying-signatures) before processing events in production.
172 </Callout>
173
174 ## Endpoints
175
176 <ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"Create webhook subscription","href":"/reference/v3/api-reference/webhook-subscriptions/postWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"List webhook subscriptions","href":"/reference/v3/api-reference/webhook-subscriptions/getWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Get webhook subscription","href":"/reference/v3/api-reference/webhook-subscriptions/getWebhookSubscriptionsById"},{"method":"PATCH","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Update webhook subscription","href":"/reference/v3/api-reference/webhook-subscriptions/patchWebhookSubscriptionsById"},{"method":"DELETE","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Delete webhook subscription","href":"/reference/v3/api-reference/webhook-subscriptions/deleteWebhookSubscriptionsById"},{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions/{id}/rotate_secret","pathV3":"/api/v3/webhook_subscriptions/{id}/rotate_secret","summary":"Rotate webhook secret","href":"/reference/v3/api-reference/webhook-subscriptions/postWebhookSubscriptionsByIdRotateSecret"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/event_types","pathV3":"/api/v3/webhook_subscriptions/event_types","summary":"List available event types","href":"/reference/v3/api-reference/webhook-subscriptions/getWebhookSubscriptionsEventTypes"}]} />