1
+---
2
+title: Configuring webhook endpoints
3
+description: One-time setup for V2 toolkits — create a dedicated ingress URL per OAuth app, store the signing secret, and point the provider at it
4
+keywords: [webhook endpoints, V2, slack, ingress, signing secret, app token, signature verification]
5
+---
6
+
7
+Some toolkits — currently **Slack**, with more arriving on the same model — deliver events at the OAuth-app level rather than per-user. For these toolkits, you need to create a `webhook_endpoint` once per OAuth app, store the provider's signing secret on it, and point the provider's app dashboard at the URL Composio returns.
8
+
9
+This is the only piece of trigger setup that's not automatic. Once it's done, [creating triggers](/docs/setting-up-triggers/creating-triggers) and [subscribing to events](/docs/setting-up-triggers/subscribing-to-events) work the same as for any other toolkit.
10
+
11
+<Callout>
12
+Most toolkits don't need this — Composio registers per-user webhooks with the provider automatically when you create a trigger. See the [delivery models](/docs/triggers#three-delivery-models) table for which model your toolkit uses. If yours is **user-level webhook** or **polling**, skip this page entirely.
13
+</Callout>
14
+
15
+## What a webhook endpoint is
16
+
17
+A `webhook_endpoint` is a project-scoped resource keyed by `(toolkit_slug, project_id, client_id)`. It exposes one ingress URL containing a random `we_*` identifier:
18
+
19
+```
20
+https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
21
+```
22
+
23
+Provider events posted to this URL are verified at ingress against the signing secret stored on the endpoint, then fanned out only to trigger instances on that endpoint's project. Unsigned or tampered requests are rejected before any trigger fires.
24
+
25
+<Callout type="warn">
26
+**OAuth apps are project-scoped on V2.** A `webhook_endpoint` ties one OAuth app (`client_id`) to exactly one project. If you share a single OAuth app across multiple Composio projects today, either consolidate to one project or register separate OAuth apps per project before creating a V2 endpoint. The provider dashboard accepts only one callback URL per OAuth app, so a single OAuth app cannot feed multiple projects on V2. See the [V2 announcement](/docs/changelog/2026/04/27#heads-up-oauth-apps-are-project-scoped-on-v2) for the full reasoning.
27
+</Callout>
28
+
29
+## End-to-end setup (Slack)
30
+
31
+The flow below uses Slack because it's the first toolkit on V2. Substitute `slack` with any other V2 toolkit slug as more come online — the API surface is identical.
32
+
33
+<Steps>
34
+<Step>
35
+### Discover required fields
36
+
37
+Each V2 toolkit has its own list of secrets it needs (signing secret, optionally an app-level token, etc.). Fetch the schema before creating the endpoint so you know what to collect from the provider's dashboard:
38
+
39
+```bash
40
+curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
41
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
42
+```
43
+
44
+Sample response:
45
+
46
+```json
47
+{
48
+ "toolkit_slug": "slack",
49
+ "setup_fields": {
50
+ "webhook_signing_secret": {
51
+ "display_name": "Signing Secret",
52
+ "description": "Webhook request signing secret from your Slack app dashboard",
53
+ "is_required": true,
54
+ "is_secret": true
55
+ },
56
+ "app_token": {
57
+ "display_name": "App-Level Token",
58
+ "description": "Slack xapp- token with authorizations:read scope for event authorization",
59
+ "is_required": true,
60
+ "is_secret": true
61
+ }
62
+ }
63
+}
64
+```
65
+
66
+</Step>
67
+<Step>
68
+### Create the endpoint
69
+
70
+```bash
71
+curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
72
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
73
+ -H "Content-Type: application/json" \
74
+ -d '{
75
+ "toolkit_slug": "slack",
76
+ "client_id": "<YOUR_SLACK_CLIENT_ID>"
77
+ }'
78
+```
79
+
80
+Sample response:
81
+
82
+```json
83
+{
84
+ "id": "we_abc123",
85
+ "toolkit_slug": "slack",
86
+ "client_id": "<YOUR_SLACK_CLIENT_ID>",
87
+ "webhook_url": "https://backend.composio.dev/api/v3.1/webhook_ingress/slack/we_abc123/trigger_event",
88
+ "data": null,
89
+ "created_at": "2026-04-24T10:00:00.000Z"
90
+}
91
+```
92
+
93
+Hold on to two values from the response: `id` (used as `<ENDPOINT_ID>` below) and `webhook_url` (you'll paste this into the provider's dashboard in step 5).
94
+
95
+<Callout>
96
+The call is **idempotent per `(toolkit_slug, client_id)` within a project** — calling it again with the same pair returns the existing endpoint without rotating the URL or wiping the secret.
97
+</Callout>
98
+</Step>
99
+<Step>
100
+### Store the signing secret
101
+
102
+```bash
103
+curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
104
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
105
+ -H "Content-Type: application/json" \
106
+ -d '{
107
+ "data": {
108
+ "webhook_signing_secret": "<YOUR_SLACK_SIGNING_SECRET>"
109
+ }
110
+ }'
111
+```
112
+
113
+For Slack, the signing secret lives at **Slack app → Basic Information → App Credentials → Signing Secret**.
114
+
115
+<Callout type="warn">
116
+**Store the signing secret before switching the provider's callback URL.** If the provider posts to a V2 URL without a secret available, every request fails with `400` and the provider may auto-disable the endpoint. Slack, for example, disables URLs after ~36 hours of consecutive failures.
117
+</Callout>
118
+</Step>
119
+<Step>
120
+### Add an app-level token (Slack-specific, optional)
121
+
122
+Slack uses an app-level token to resolve which connected user is authorized for a given event. This unlocks events that aren't otherwise scoped to a single user — DMs, private channels, and reactions:
123
+
124
+- `SLACK_DIRECT_MESSAGE_RECEIVED` — always required.
125
+- `SLACK_CHANNEL_MESSAGE_RECEIVED` — required for **private channels** and **multi-person DMs**; public-channel messages are delivered without it.
126
+- `SLACK_MESSAGE_REACTION_ADDED` — always required (reactions don't carry channel-type metadata, so per-user authorization runs unconditionally).
127
+
128
+Skip this step if you only need public-channel messages today. You can add the token later by re-running the `PATCH` below.
129
+
130
+```bash
131
+curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
132
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
133
+ -H "Content-Type: application/json" \
134
+ -d '{
135
+ "data": {
136
+ "app_token": "xapp-..."
137
+ }
138
+ }'
139
+```
140
+
141
+Generate the token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
142
+
143
+<Callout>
144
+**Other V2 toolkits will have different secondary fields.** Always read `setup_fields` from the schema endpoint (step 1) — the field names, descriptions, and which are required are the source of truth.
145
+</Callout>
146
+</Step>
147
+<Step>
148
+### Point the provider's app dashboard at the V2 URL
149
+
150
+For Slack, set **Event Subscriptions → Request URL** to the `webhook_url` returned in step 2. Composio responds to Slack's `url_verification` challenge automatically — you don't need to write any handshake code on your side.
151
+
152
+The same applies to other providers Composio supports on V2: Composio handles the verification challenge (Asana `X-Hook-Secret`, Outlook validation tokens, and so on) so the URL verifies on first save.
153
+</Step>
154
+<Step>
155
+### Confirm the endpoint is verified
156
+
157
+```bash
158
+curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
159
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
160
+```
161
+
162
+A populated `verified_at` timestamp on the response means the provider has successfully completed the handshake against your endpoint. Once `verified_at` is set, you can [create V2 trigger instances](/docs/setting-up-triggers/creating-triggers) that route through this endpoint.
163
+</Step>
164
+</Steps>
165
+
166
+## Updating an endpoint
167
+
168
+Use `PATCH` to update one field at a time (e.g. rotate just the signing secret):
169
+
170
+```bash
171
+curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
172
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
173
+ -H "Content-Type: application/json" \
174
+ -d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>" } }'
175
+```
176
+
177
+Use `POST` to **replace** `data` wholesale — any field you don't include is cleared:
178
+
179
+```bash
180
+curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
181
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
182
+ -H "Content-Type: application/json" \
183
+ -d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>", "app_token": "<NEW_APP_TOKEN>" } }'
184
+```
185
+
186
+The `webhook_url` itself is immutable — it's tied to the endpoint's `we_*` id for the lifetime of the endpoint. Rotating the signing secret on the provider side is a `PATCH` on the existing endpoint, not a new endpoint.
187
+
188
+## Listing endpoints
189
+
190
+```bash
191
+curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
192
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
193
+```
194
+
195
+Returns every endpoint in the current project with `verified_at` populated for the ones that have completed the handshake. Use this when you're operating across many OAuth apps and want a quick health view.
196
+
197
+## Migrating from V1
198
+
199
+If you already have V1 trigger instances running, your existing setup is unchanged — V1 ingress URLs (`/api/v3/trigger_instances/{toolkit}/{project_id}/handle`) are not deprecated and every legacy slug (`SLACK_RECEIVE_*`, `SLACKBOT_*`, etc.) keeps routing through V1.
200
+
201
+You only need to set up a V2 webhook endpoint in two cases:
202
+
203
+1. **You want to use a V2 trigger slug.** For Slack, that's `SLACK_CHANNEL_MESSAGE_RECEIVED`, `SLACK_DIRECT_MESSAGE_RECEIVED`, or `SLACK_MESSAGE_REACTION_ADDED`. Without an endpoint, the upsert call returns `400`.
204
+2. **You want to consolidate an OAuth app onto V2.** Pick the project that should own the OAuth app on V2, set up an endpoint there, and update the provider's callback URL.
205
+
206
+Even outside these cases, moving an OAuth app to V2 is recommended for the security wins — ingress signature verification, project-scoped fan-out, and per-user authorization for app-level events. See the [V2 announcement](/docs/changelog/2026/04/27) for the full migration walkthrough and the V1 → V2 slug mapping for Slack.
207
+
208
+## What to read next
209
+
210
+<Cards>
211
+ <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances once your endpoint is configured" />
212
+ <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Set up the URL Composio delivers events to" />
213
+ <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify the signature on every Composio-to-your-endpoint delivery" />
214
+</Cards>