11
| Change | Action required |
12
|---|---|
13
| New `webhook_endpoints` API | None (opt-in) |
14
-| New ingress path `/api/v3/webhook_ingress/{toolkit}/{we_*}/trigger_event` | 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 |
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/webhook_ingress/{toolkit}/{we_xxx}/trigger_event
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.
38
39
| Method | Path | Purpose |
40
|---|---|---|
41
-| `GET` | `/api/v3/webhook_endpoints/schema?toolkit_slug={slug}` | List required setup fields for a toolkit |
42
-| `POST` | `/api/v3/webhook_endpoints` | Create an endpoint (idempotent per `toolkit_slug + client_id` within a project) |
43
-| `GET` | `/api/v3/webhook_endpoints` | List endpoints in the current project |
44
-| `GET` | `/api/v3/webhook_endpoints/{id}` | Get a single endpoint, including `verified_at` |
45
-| `POST` | `/api/v3/webhook_endpoints/{id}` | Replace `setup_data` |
46
-| `PATCH` | `/api/v3/webhook_endpoints/{id}` | Update one or more fields in `setup_data` |
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/webhook_ingress/{toolkit_slug}/{webhook_endpoint_nano_id}/trigger_event` |
52
+| `POST` | `/api/v3.1/webhook_ingress/{toolkit_slug}/{webhook_endpoint_nano_id}/trigger_event` |
53
54
## Migration walkthrough (Slack)
55
58
### 1. Discover required fields
59
60
```bash
61
-curl "https://backend.composio.dev/api/v3/webhook_endpoints/schema?toolkit_slug=slack" \
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
87
### 2. Create the endpoint
88
89
```bash
90
-curl -X POST "https://backend.composio.dev/api/v3/webhook_endpoints" \
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" }'
100
"id": "we_abc123",
101
"toolkit_slug": "slack",
102
"client_id": "YOUR_SLACK_CLIENT_ID",
103
- "webhook_url": "https://backend.composio.dev/api/v3/webhook_ingress/slack/we_abc123/trigger_event",
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
}
111
### 3. Store the signing secret
112
113
```bash
114
-curl -X PATCH "https://backend.composio.dev/api/v3/webhook_endpoints/ENDPOINT_ID" \
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" } }'
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/webhook_endpoints/ENDPOINT_ID" \
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-..." } }'
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/trigger_instances/SLACK_CHANNEL_MESSAGE_RECEIVED/upsert" \
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 '{