Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs(changelog): bump V2 webhook trigger examples from /api/v3 to /api/v3.1
We're standardising customer-facing API examples on /api/v3.1 across the docs. Apollo's proxy already rewrites /api/v3.1/{webhook_endpoints, webhook_ingress,trigger_instances} to /api/v3, so all examples in this entry are functionally identical — just consistent with the rest of the docs. The legacy V1 ingress URL reference is left at /api/v3 because that reflects what existing V1 customers actually have registered with their providers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Anshu Garg committed
Apr 27, 2026 at 17:15 UTC
43a689dc6cbe5187f175dd13e9dbd8cee6990b2c
1 file changed
+15
-15
docs/content/changelog/04-27-26-webhook-triggers-v2.mdx
+15
-15
@@ -11,7 +11,7 @@ Webhook Triggers V2 introduces a first-class `webhook_endpoints` resource with a
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,7 +21,7 @@ Webhook Triggers V2 introduces a first-class `webhook_endpoints` resource with a
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,18 +38,18 @@ All endpoints require a project API key (`x-api-key`).
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,7 +58,7 @@ Slack is the first toolkit on V2. The same flow applies to every toolkit added l
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,7 +87,7 @@ Sample response:
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,7 +100,7 @@ Sample response:
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,7 +111,7 @@ Hold on to two values from the response: `id` (used as `ENDPOINT_ID` in the next
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,7 +131,7 @@ The app-level token is what lets Composio resolve per-user authorization for Sla
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,7 +154,7 @@ Three new Slack triggers go live on V2 today, with more to follow on V2 — both
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 '{