Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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. |