@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 197 lines 9.98 KB
Raw
1 ---
2 title: "Webhook Triggers V2"
3 description: "Dedicated webhook endpoint per OAuth app, ingress-level signature verification, per-user authorization for private channels and DMs, and config-level event filters. Opt-in; V1 is unchanged."
4 date: "2026-04-27"
5 ---
6
7 Webhook Triggers V2 introduces a first-class `webhook_endpoints` resource with a dedicated ingress URL per OAuth app. V2 is **opt-in** and scoped to new trigger slugs — existing V1 triggers, URLs, and payload formats are unchanged.
8
9 ## Summary
10
11 | Change | Action required |
12 |---|---|
13 | New `webhook_endpoints` API | None (opt-in) |
14 | New ingress path `/api/v3.1/webhook_ingress/{toolkit}/{we_*}/trigger_event` | None (opt-in) |
15 | Ingress-level signature verification | Automatic for V2 endpoints |
16 | New Slack V2 slugs (`SLACK_CHANNEL_MESSAGE_RECEIVED`, `SLACK_DIRECT_MESSAGE_RECEIVED`, `SLACK_MESSAGE_REACTION_ADDED`) | Opt-in |
17 | V1 ingress path and all legacy trigger slugs | None — unchanged |
18
19 ## What's in V2
20
21 **Dedicated endpoint per OAuth app.** Each `webhook_endpoint` is keyed by `(toolkit_slug, project_id, client_id)` and exposes its own URL containing a random `we_*` identifier:
22
23 ```
24 https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit}/{we_xxx}/trigger_event
25 ```
26
27 This replaces V1's shared `/handle` URL per toolkit. Events arriving on a V2 URL are fanned out only to trigger instances on that endpoint's project.
28
29 **Signature verification at ingress.** Composio cryptographically verifies every V2 request against the signing secret stored on the endpoint, using HMAC-SHA256, Ed25519, or shared-token matching depending on the toolkit. Unsigned or tampered payloads are rejected, so third parties cannot spoof events onto your triggers. For providers that sign a request timestamp (e.g. Slack), replay protection additionally rejects requests whose timestamp falls outside the allowed skew window.
30
31 **Per-user authorization for app-level events.** On toolkits with per-user visibility — Slack being the first — V2 uses an app-level token (for Slack, an `xapp-…` token with `authorizations:read`) to resolve which connected users are authorized for a given event, so only those users' triggers fire. This underpins a new class of triggers for private channels, direct messages, and other per-recipient events, each routed only to the user the event was intended for.
32
33 **Automatic handshakes and cleanup.** Composio responds to provider verification challenges — Slack `url_verification`, Asana `X-Hook-Secret`, Outlook validation tokens, and so on — so callback URLs verify without any custom code. User-level webhooks are also deregistered on the provider side when the trigger is deleted.
34
35 ## API reference
36
37 All endpoints require a project API key (`x-api-key`).
38
39 | Method | Path | Purpose |
40 |---|---|---|
41 | `GET` | `/api/v3.1/webhook_endpoints/schema?toolkit_slug={slug}` | List required setup fields for a toolkit |
42 | `POST` | `/api/v3.1/webhook_endpoints` | Create an endpoint (idempotent per `toolkit_slug + client_id` within a project) |
43 | `GET` | `/api/v3.1/webhook_endpoints` | List endpoints in the current project |
44 | `GET` | `/api/v3.1/webhook_endpoints/{id}` | Get a single endpoint, including `verified_at` |
45 | `POST` | `/api/v3.1/webhook_endpoints/{id}` | Replace `setup_data` |
46 | `PATCH` | `/api/v3.1/webhook_endpoints/{id}` | Update one or more fields in `setup_data` |
47
48 Provider events are posted to:
49
50 | Method | Path |
51 |---|---|
52 | `POST` | `/api/v3.1/webhook_ingress/{toolkit_slug}/{webhook_endpoint_nano_id}/trigger_event` |
53
54 ## Migration walkthrough (Slack)
55
56 Slack is the first toolkit on V2. The same flow applies to every toolkit added later.
57
58 ### 1. Discover required fields
59
60 ```bash
61 curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
62 -H "x-api-key: YOUR_API_KEY"
63 ```
64
65 Sample response:
66
67 ```json
68 {
69 "toolkit_slug": "slack",
70 "setup_fields": {
71 "webhook_signing_secret": {
72 "display_name": "Signing Secret",
73 "description": "Webhook request signing secret from your Slack app dashboard",
74 "is_required": true,
75 "is_secret": true
76 },
77 "app_token": {
78 "display_name": "App-Level Token",
79 "description": "Slack xapp- token with authorizations:read scope for event authorization",
80 "is_required": true,
81 "is_secret": true
82 }
83 }
84 }
85 ```
86
87 ### 2. Create the endpoint
88
89 ```bash
90 curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
91 -H "x-api-key: YOUR_API_KEY" \
92 -H "Content-Type: application/json" \
93 -d '{ "toolkit_slug": "slack", "client_id": "YOUR_SLACK_CLIENT_ID" }'
94 ```
95
96 Sample response:
97
98 ```json
99 {
100 "id": "we_abc123",
101 "toolkit_slug": "slack",
102 "client_id": "YOUR_SLACK_CLIENT_ID",
103 "webhook_url": "https://backend.composio.dev/api/v3.1/webhook_ingress/slack/we_abc123/trigger_event",
104 "data": null,
105 "created_at": "2026-04-24T10:00:00.000Z"
106 }
107 ```
108
109 Hold on to two values from the response: `id` (used as `ENDPOINT_ID` in the next steps) and `webhook_url` (the URL you'll paste into your Slack app dashboard in step 5). The call is idempotent — calling it again with the same `toolkit_slug` and `client_id` returns the existing endpoint.
110
111 ### 3. Store the signing secret
112
113 ```bash
114 curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID" \
115 -H "x-api-key: YOUR_API_KEY" \
116 -H "Content-Type: application/json" \
117 -d '{ "data": { "webhook_signing_secret": "YOUR_SIGNING_SECRET" } }'
118 ```
119
120 <Callout type="warn">
121 Store the signing secret before switching the provider's callback URL. If Slack posts to a V2 URL without a secret available, every request fails with `400` and Slack may auto-disable the endpoint after ~36 hours of failures.
122 </Callout>
123
124 ### 4. Add an app-level token for private-scope events
125
126 The app-level token is what lets Composio resolve per-user authorization for Slack's private-scope events.
127
128 - `SLACK_DIRECT_MESSAGE_RECEIVED` always requires it.
129 - `SLACK_CHANNEL_MESSAGE_RECEIVED` requires it for events from **private channels** and **multi-person DMs**; public-channel messages are delivered without it.
130
131 Skip this step if you only need public-channel messages today — you can add the token later.
132
133 ```bash
134 curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID" \
135 -H "x-api-key: YOUR_API_KEY" \
136 -H "Content-Type: application/json" \
137 -d '{ "data": { "app_token": "xapp-..." } }'
138 ```
139
140 Generate the token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
141
142 ### 5. Point your Slack app at the V2 URL
143
144 Set **Event Subscriptions → Request URL** in your Slack app to the `webhook_url` returned in step 2. Composio verifies the endpoint with Slack automatically — no extra action needed on your side.
145
146 ### 6. Create V2 trigger instances
147
148 Three new Slack triggers go live on V2 today, with more to follow on V2 — both for Slack and for other toolkits. The table below maps your existing V1 slugs to the new V2 equivalents:
149
150 | V1 slug (still supported) | V2 replacement | `app_token` required? |
151 |---|---|---|
152 | `SLACK_RECEIVE_MESSAGE` | `SLACK_CHANNEL_MESSAGE_RECEIVED` | Only for private channels and multi-person DMs; public channels work without it |
153 | `SLACK_RECEIVE_DIRECT_MESSAGE` | `SLACK_DIRECT_MESSAGE_RECEIVED` | Always |
154 | `SLACK_REACTION_ADDED` | `SLACK_MESSAGE_REACTION_ADDED` | Always (reactions don't carry channel type, so per-user authz runs unconditionally) |
155
156 ```bash
157 curl -X POST "https://backend.composio.dev/api/v3.1/trigger_instances/SLACK_CHANNEL_MESSAGE_RECEIVED/upsert" \
158 -H "x-api-key: YOUR_API_KEY" \
159 -H "Content-Type: application/json" \
160 -d '{
161 "connected_account_id": "CONNECTED_ACCOUNT_ID",
162 "trigger_config": {}
163 }'
164 ```
165
166 ## Heads up: OAuth apps are project-scoped on V2
167
168 <Callout type="warn">
169 **Action required if you share a single OAuth app across multiple Composio projects or organizations today.** V2 ties each OAuth app (`client_id`) to exactly one project. Before moving such an app to V2, either consolidate to a single project or register separate OAuth apps per project.
170 </Callout>
171
172 The provider dashboard accepts only one callback URL per OAuth app, and each V2 URL resolves to exactly one project — so a single OAuth app cannot feed multiple projects on V2.
173
174 The signing secret also lives on the endpoint, so the reverse holds too: two different OAuth apps cannot share one V2 endpoint — Composio only verifies signatures against the secret stored on that endpoint, so requests signed by a different OAuth app would be rejected.
175
176 In return, every project graduates to a first-class webhook tenant on V2 — with its own:
177
178 - Ingress rate-limit and backpressure budget
179 - Clean fan-out — events reach only that project's trigger instances
180 - Signing secret and app-level token, scoped to this project alone
181 - Per-project metering and billing
182
183 Your V1 endpoints are unaffected. Any OAuth app you leave on V1 continues to work across projects exactly as it does today.
184
185 ## Backward compatibility
186
187 **Everything you have today keeps working — same URLs, same trigger slugs, same payload shapes, no data migration.**
188
189 - The V1 ingress URL (`/api/v3/trigger_instances/{toolkit}/{project_id}/handle`) is not deprecated.
190 - Every existing trigger slug — `SLACK_RECEIVE_*`, `SLACKBOT_*`, and the equivalent legacy slugs on other toolkits — continues to route through V1.
191
192 You only need to set up a V2 webhook endpoint in two cases:
193
194 1. **You want to use one of the new V2 trigger slugs** (e.g. `SLACK_CHANNEL_MESSAGE_RECEIVED`, `SLACK_DIRECT_MESSAGE_RECEIVED`). A V2 endpoint is required at setup; without one, the upsert returns `400`.
195 2. **You want to move an OAuth app that's currently shared across multiple projects or organizations onto V2.** Pick the project that should own it on V2 and set up an endpoint there, or register separate OAuth apps per project (see [Heads up: OAuth apps are project-scoped on V2](#heads-up-oauth-apps-are-project-scoped-on-v2)).
196
197 Even outside these two cases, we recommend moving your OAuth apps to V2 at your own pace. Every endpoint you migrate inherits the signature verification, ingress isolation, and per-user authorization called out above.