@devries-cameron20 / composio Mirror · read-only / commits / 68390b0cd
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, 21:00 UTC

docs(triggers): unify around one webhook-endpoint concept; drop V1/V2 framing

Per review: the conceptual docs should describe the current product — one webhook-endpoint concept whose only axis is who configures it. V1/V2 split was an implementation detail that didn't belong in user- facing prose. Per-OAuth-app endpoint setup also doesn't apply when you use Composio-managed credentials, which the previous draft failed to call out. Concrete changes vs the previous commit: - Drop "V1", "V2", "user-level webhook", "app-level webhook endpoint", and "delivery models" from all conceptual docs (triggers.mdx, creating-triggers.mdx, subscribing-to-events.mdx, webhook-verification.mdx, troubleshooting/triggers.mdx, glossary.mdx). - Remove the standalone configuring-webhook-endpoints.mdx page; fold the walkthrough into creating-triggers.mdx as a "Configuring the webhook endpoint" section. Revert meta.json accordingly. - triggers.mdx now frames a single webhook-endpoint concept with two configurations: Composio-managed (default for everything; required with Composio-managed OAuth apps) vs you-managed (your own OAuth app on toolkits like Slack and Notion today). - Make the Composio-managed-OAuth case explicit: if you use Composio-managed credentials, no manual webhook-endpoint setup applies. Surfaced as a callout in triggers.mdx and creating-triggers.mdx. - The schema endpoint (GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=...) is documented as the source of truth for whether your toolkit needs manual configuration: empty setup_fields = Composio handles it (Asana, etc.); non-empty = you handle it (Slack, Notion). - creating-triggers.mdx: walkthrough now uses 5 numbered steps (discover → create → store credentials → point provider at URL → confirm verified_at), plus an "Updating an endpoint" subsection covering PATCH vs POST semantics and how to list endpoints. - troubleshooting/triggers.mdx: section header drops "V2", lead with a one-line note that issues only apply to user-managed endpoints. - glossary.mdx: Trigger entry simplified to two delivery types; Webhook Endpoint entry rewritten without V2 vocabulary. - webhook-verification.mdx: ingress section drops "V2" framing and explains the two cases for where the signing secret comes from (Composio-managed credentials vs PATCHed by the user). Note: the schema endpoint is referenced in the docs but is not in Apollo's exported OpenAPI spec, so no auto-generated reference page exists for it. CRUD on /webhook_endpoints is in the spec and will surface via auto-update PR #3238. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 17:19 UTC 68390b0cd974b08376c3236043e58a5a6d3e493b
8 files changed +235 -265
docs/content/docs/glossary.mdx
+2 -2
@@ -116,7 +116,7 @@ Pinning a toolkit to a specific version so your integration uses a consistent se
116 </GlossaryTerm>
117
118 <GlossaryTerm name="Trigger">
119 -Sends structured payloads to your application when something happens in a connected app. Three delivery models: **polling** (Composio polls the provider, e.g. Gmail), **user-level webhook** (Composio auto-registers a per-user webhook with the provider, e.g. Asana, GitHub), and **app-level webhook endpoint** (V2; you configure a webhook endpoint per OAuth app, e.g. Slack). See [Triggers](/docs/triggers).
119 +Sends structured payloads to your application when something happens in a connected app. Two delivery types: **webhook** (the provider pushes events in real time, e.g. Slack, GitHub, Asana) and **polling** (Composio polls the provider on a schedule, e.g. Gmail). See [Triggers](/docs/triggers).
120 </GlossaryTerm>
121
122 <GlossaryTerm name="Trigger Instance">
@@ -124,7 +124,7 @@ A specific, active trigger scoped to a user's connected account.
124 </GlossaryTerm>
125
126 <GlossaryTerm name="Webhook Endpoint">
127 -A V2 ingress URL Composio creates per OAuth app for toolkits where the provider posts events at the app level (currently Slack). Stores the provider's signing secret so Composio can verify every inbound request before fanning out to triggers. See [Configuring webhook endpoints](/docs/setting-up-triggers/configuring-webhook-endpoints).
127 +The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures the endpoint for you in most cases; for some toolkits (today: Slack, Notion) when you bring your own OAuth app, you configure it yourself. See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
128 </GlossaryTerm>
129
130 <GlossaryTerm name="Webhook Subscription">
docs/content/docs/setting-up-triggers/configuring-webhook-endpoints.mdx deleted
-214
@@ -1,214 +0,0 @@
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>
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+163 -5
@@ -1,7 +1,7 @@
1 ---
2 title: Creating triggers
3 -description: Create trigger instances via the dashboard or SDK
4 -keywords: [triggers, create trigger, trigger config]
3 +description: Configure the webhook endpoint when needed, then create trigger instances via the dashboard or SDK
4 +keywords: [triggers, create trigger, trigger config, webhook endpoint, signing secret]
5 ---
6
7 Create a trigger to start receiving events. A trigger watches for a specific event (e.g., `GITHUB_COMMIT_EVENT`) on a specific user's connected account. For an overview of how triggers work, see [Triggers](/docs/triggers).
@@ -10,10 +10,168 @@ Create a trigger to start receiving events. A trigger watches for a specific eve
10 Before creating triggers, ensure you have:
11 - An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
12 - A connected account for the user whose events you want to capture
13 -- For V2 toolkits (Slack today), a [webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints) configured for the OAuth app — without it, the upsert call returns `400`. See the [delivery models](/docs/triggers#three-delivery-models) table to check whether your toolkit needs this.
13 +- For toolkits where you need to register the webhook endpoint yourself (today: Slack and Notion, when you bring your own OAuth app), the [webhook endpoint configured](#configuring-the-webhook-endpoint) before you create any triggers — see the section below to check whether yours applies.
14 </Callout>
15
16 -You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard).
16 +## Configuring the webhook endpoint
17 +
18 +For a webhook trigger to fire, the provider has to know where to post events. For most toolkits, Composio handles this for you — you don't see or set up anything. For a small set of toolkits (today: **Slack** and **Notion**, with more arriving on the same flow), you set up a `webhook_endpoint` once per OAuth app: paste the provider's signing secret onto it, take the URL Composio returns, and paste that URL into the provider's app dashboard.
19 +
20 +<Callout>
21 +**You only do this if you bring your own OAuth app.** With Composio-managed OAuth apps, the webhook endpoint is already provisioned and you can skip ahead to [Using the SDK](#using-the-sdk).
22 +</Callout>
23 +
24 +### Step 1: Discover whether you need to configure anything
25 +
26 +Call the schema endpoint for your toolkit. The response is the source of truth.
27 +
28 +```bash
29 +curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug={toolkit_slug}" \
30 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
31 +```
32 +
33 +- **Empty / no `setup_fields`** → Composio handles the endpoint for you (e.g. Asana). Skip the rest of this section and go to [Using the SDK](#using-the-sdk).
34 +- **One or more `setup_fields`** → You configure the endpoint yourself. The fields tell you exactly what to collect from the provider's app dashboard.
35 +
36 +Sample response for Slack:
37 +
38 +```json
39 +{
40 + "toolkit_slug": "slack",
41 + "setup_fields": {
42 + "webhook_signing_secret": {
43 + "display_name": "Signing Secret",
44 + "description": "Webhook request signing secret from your Slack app dashboard",
45 + "is_required": true,
46 + "is_secret": true
47 + },
48 + "app_token": {
49 + "display_name": "App-Level Token",
50 + "description": "Slack xapp- token with authorizations:read scope for event authorization",
51 + "is_required": true,
52 + "is_secret": true
53 + }
54 + }
55 +}
56 +```
57 +
58 +### Step 2: Create the endpoint
59 +
60 +```bash
61 +curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
62 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
63 + -H "Content-Type: application/json" \
64 + -d '{
65 + "toolkit_slug": "slack",
66 + "client_id": "<YOUR_OAUTH_CLIENT_ID>"
67 + }'
68 +```
69 +
70 +Sample response:
71 +
72 +```json
73 +{
74 + "id": "we_abc123",
75 + "toolkit_slug": "slack",
76 + "client_id": "<YOUR_OAUTH_CLIENT_ID>",
77 + "webhook_url": "https://backend.composio.dev/api/v3.1/webhook_ingress/slack/we_abc123/trigger_event",
78 + "data": null,
79 + "created_at": "2026-04-24T10:00:00.000Z"
80 +}
81 +```
82 +
83 +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 app dashboard in step 4). 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.
84 +
85 +<Callout type="warn">
86 +**A `webhook_endpoint` ties one OAuth app to exactly one project.** If you currently share an OAuth app across multiple Composio projects, either consolidate to one project or register separate OAuth apps per project before creating an endpoint — the provider dashboard accepts only one callback URL per OAuth app.
87 +</Callout>
88 +
89 +### Step 3: Store the credentials returned by the schema
90 +
91 +`PATCH` each field returned by the schema endpoint. For Slack, that's the signing secret and (when applicable) the app-level token.
92 +
93 +```bash
94 +curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
95 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
96 + -H "Content-Type: application/json" \
97 + -d '{
98 + "data": {
99 + "webhook_signing_secret": "<SIGNING_SECRET>"
100 + }
101 + }'
102 +```
103 +
104 +For Slack, the signing secret lives at **Slack app → Basic Information → App Credentials → Signing Secret**.
105 +
106 +<Callout type="warn">
107 +**Store the credentials before you switch the provider's callback URL in step 4.** If the provider posts to the URL without a secret on the endpoint, every request fails with `400`, and the provider may auto-disable the endpoint after a window of consecutive failures (Slack: ~36 hours).
108 +</Callout>
109 +
110 +For toolkits with additional fields — Slack's `app_token`, for instance, which is required for direct messages, private channels, and reactions — `PATCH` them in the same way:
111 +
112 +```bash
113 +curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
114 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
115 + -H "Content-Type: application/json" \
116 + -d '{
117 + "data": {
118 + "app_token": "xapp-..."
119 + }
120 + }'
121 +```
122 +
123 +Generate the Slack app-level token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
124 +
125 +<Callout>
126 +The schema response is the source of truth for which fields each toolkit needs. Always read `setup_fields` (step 1) for the toolkit you're configuring rather than assuming the Slack shape.
127 +</Callout>
128 +
129 +### Step 4: Point the provider's app dashboard at the URL
130 +
131 +Paste the `webhook_url` from step 2 into the provider's app dashboard:
132 +
133 +- **Slack** → Event Subscriptions → Request URL
134 +- **Notion** → Webhook Endpoints (in the integration's settings)
135 +
136 +Composio responds to the provider's verification challenge automatically (Slack `url_verification`, Notion's verification token, and so on) — you don't write any handshake code on your side.
137 +
138 +### Step 5: Confirm the endpoint is verified
139 +
140 +```bash
141 +curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
142 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
143 +```
144 +
145 +A populated `verified_at` timestamp on the response means the provider has completed the handshake. You can now create trigger instances on this OAuth app.
146 +
147 +### Updating an endpoint
148 +
149 +To rotate the signing secret or update any single field, `PATCH` it (other fields are preserved):
150 +
151 +```bash
152 +curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
153 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
154 + -H "Content-Type: application/json" \
155 + -d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>" } }'
156 +```
157 +
158 +To **replace** `data` wholesale (any field you don't include is cleared), `POST` to the same URL:
159 +
160 +```bash
161 +curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
162 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
163 + -H "Content-Type: application/json" \
164 + -d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>", "app_token": "<NEW_APP_TOKEN>" } }'
165 +```
166 +
167 +The `webhook_url` itself is immutable for the lifetime of the endpoint — rotating the signing secret on the provider side is a `PATCH` on the existing endpoint, not a new one.
168 +
169 +To list every endpoint in the current project (useful when operating across many OAuth apps):
170 +
171 +```bash
172 +curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
173 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
174 +```
175
176 ## Using the SDK
177
@@ -90,7 +248,7 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses
248 ## What to read next
249
250 <Cards>
93 - <Card icon={<RouteIcon />} title="Configuring webhook endpoints" href="/docs/setting-up-triggers/configuring-webhook-endpoints" description="Required for V2 toolkits (Slack today): register the provider's signing secret and ingress URL" />
251 <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
252 + <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures so you know payloads came from Composio" />
253 <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
254 </Cards>
docs/content/docs/setting-up-triggers/meta.json
-1
@@ -2,7 +2,6 @@
2 "title": "Using Triggers",
3 "pages": [
4 "creating-triggers",
5 - "configuring-webhook-endpoints",
5 "subscribing-to-events",
6 "managing-triggers"
7 ]
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+1 -1
@@ -7,7 +7,7 @@ keywords: [webhooks, subscribe, events, webhook payload, V3]
7 <Callout>
8 Two webhook URLs sit on opposite sides of Composio — keep them distinct in your head.
9
10 -- **Provider → Composio (ingress).** Composio handles this for you. For most toolkits there's nothing to do; for V2 toolkits like Slack you [configure a webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints) once per OAuth app.
10 +- **Provider → Composio (ingress).** A webhook endpoint per OAuth app — Composio configures it for you in most cases. When you bring your own OAuth app on a toolkit like Slack or Notion, you [configure the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) once per OAuth app.
11 - **Composio → your application (subscription).** This page covers this side: you tell Composio which URL to deliver events to, and Composio signs every request.
12 </Callout>
13
docs/content/docs/triggers.mdx
+53 -29
@@ -1,40 +1,56 @@
1 ---
2 title: Triggers
3 description: Understand how Composio delivers event data from connected apps
4 -keywords: [triggers, webhooks, events, polling, webhook endpoints, concepts]
4 +keywords: [triggers, webhooks, events, polling, webhook endpoint, concepts]
5 ---
6
7 When events occur in apps, like a new Slack message, a GitHub commit, or an incoming email, triggers send event data to your application as structured payloads.
8
9 <Figure src="/images/triggers-flow.svg" srcDark="/images/triggers-flow-dark.svg" alt="Triggers flow: Connected apps send events to Composio, which delivers them to your webhook endpoint via HTTP POST" caption="How triggers deliver events from apps to your application" />
10
11 -## Three delivery models
11 +## Two delivery types
12
13 -Every Composio trigger fits one of three delivery models. The model is a property of the trigger type, not something you choose — but knowing which model your trigger uses tells you exactly what setup is required.
13 +| Type | What happens | Examples |
14 +|---|---|---|
15 +| **Webhook** | The provider posts events to a Composio-issued ingress URL in real time. Composio verifies the provider's signature, then fans the event out to matching trigger instances. | Slack, GitHub, Asana, Notion, Outlook, ... |
16 +| **Polling** | Composio polls the provider on a schedule. Composio managed auth has a 15-minute minimum interval; expect that as the worst-case delay between source event and delivery. | Gmail |
17 +
18 +The delivery type is a property of the trigger type, not something you choose.
19 +
20 +## Webhook endpoints
21
15 -| Delivery model | What Composio does | What you do |
22 +Every webhook trigger routes through a **webhook endpoint** — a project-scoped resource that owns the ingress URL the provider posts to and the signing secret used to verify each request. Endpoints are keyed by `(toolkit_slug, project_id, client_id)`, so each OAuth app gets its own URL:
23 +
24 +```
25 +https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
26 +```
27 +
28 +There are two ways an endpoint gets configured:
29 +
30 +| Configuration | When it applies | What you do |
31 |---|---|---|
17 -| **Polling** | Composio polls the provider on a schedule (15-minute minimum on Composio managed auth) | Just create the trigger |
18 -| **User-level webhook** | Composio registers a per-user webhook with the provider when you create the trigger, and deregisters it when you delete the trigger | Just create the trigger |
19 -| **App-level webhook endpoint** | Composio gives you one ingress URL per OAuth app; you point the provider's app dashboard at it once | Configure a [webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints) for the OAuth app, then create triggers normally |
32 +| **Composio configures it for you** | Composio-managed OAuth apps (any toolkit) **or** your own OAuth app on a toolkit Composio can register webhooks for on your behalf using the connected user's credentials (e.g. **Asana**) | Nothing — endpoint setup, signature verification, and provider-side registration happen automatically when you create the trigger |
33 +| **You configure it** | Your own OAuth app on a toolkit whose provider posts events at the OAuth-app level (today: **Slack** and **Notion**; more toolkits will follow on this same flow) | Once per OAuth app, before creating triggers — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) |
34
21 -<Accordions>
22 -<Accordion title="Which model does each toolkit use?">
23 -- **Polling** — toolkits without outbound webhooks (e.g. Gmail).
24 -- **User-level webhook** — most webhook-capable toolkits (Asana, Outlook, GitHub repo events, and so on). Composio handles the provider-side webhook lifecycle for you.
25 -- **App-level webhook endpoint** (V2) — toolkits whose providers post events at the OAuth-app level rather than per-user, currently **Slack**. More toolkits will move to V2 over time. See [Webhook Triggers V2](/docs/changelog/2026/04/27) for the full announcement.
26 -</Accordion>
27 -<Accordion title="What is a trigger type?">
28 -A trigger type is a template that defines what event to listen for and what configuration is required. For example, `GITHUB_COMMIT_EVENT` requires an `owner` and `repo`. Each toolkit exposes its own set of trigger types.
29 -</Accordion>
30 -<Accordion title="What is a trigger instance?">
31 -When you create a trigger from a type, it's scoped to a specific [user and connected account](/docs/users-and-sessions). For example, creating a `GITHUB_COMMIT_EVENT` trigger for user `alice` on the `composio` repo produces a trigger instance with its own `ti_*` ID that you can enable, disable, or delete independently.
32 -</Accordion>
33 -</Accordions>
35 +<Callout>
36 +**If you use Composio-managed credentials, you don't need to configure anything — skip ahead to [Creating triggers](/docs/setting-up-triggers/creating-triggers).** Manual webhook-endpoint setup only applies when you bring your own OAuth app.
37 +</Callout>
38 +
39 +### Checking which case applies to your toolkit
40 +
41 +The single source of truth is the schema endpoint. Call it for the toolkit you're integrating; the response tells you exactly what to do.
42 +
43 +```bash
44 +curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug={toolkit_slug}" \
45 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
46 +```
47 +
48 +- **`setup_fields` is empty / not present** → Composio configures the endpoint for you. Nothing to do.
49 +- **`setup_fields` lists one or more fields** → You configure the endpoint. The fields tell you what credentials to collect from the provider (signing secret, app-level token, etc.). Today this applies to **Slack** and **Notion**; the list will grow as more toolkits move onto this flow.
50
51 ## End-to-end flow
52
37 -For every trigger, regardless of delivery model, events take the same path on the way to your application:
53 +For every webhook trigger, an event takes the same path on the way to your application:
54
55 ```
56 provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpoint
@@ -44,25 +60,25 @@ Two webhook URLs sit on opposite sides of Composio. Don't confuse them:
60
61 | URL | Direction | Who configures it |
62 |---|---|---|
47 -| **Ingress** (`/api/v3.1/trigger_instances/.../handle` for V1, `/api/v3.1/webhook_ingress/...` for V2) | Provider → Composio | Composio (V1, automatic) or you, once per OAuth app (V2 — see [Configuring webhook endpoints](/docs/setting-up-triggers/configuring-webhook-endpoints)) |
63 +| **Ingress** (`/api/v3.1/webhook_ingress/...`) | Provider → Composio | Composio for most cases; you for your-own-OAuth on toolkits like Slack and Notion — see [Webhook endpoints](#webhook-endpoints) above |
64 | **Webhook subscription** (your URL) | Composio → your application | You, once per project — see [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
65
66 Composio verifies signatures on both hops:
67
52 -- On ingress, V2 endpoints verify the provider's signature against the signing secret you stored on the endpoint. Unsigned or tampered requests are rejected before any trigger fires.
53 -- On delivery, every webhook Composio sends to your endpoint is signed with your subscription secret — verify it as described in [Verifying webhooks](/docs/webhook-verification).
68 +- **At ingress**, every inbound request is verified against the signing secret on the webhook endpoint. Unsigned or tampered requests are rejected before any trigger fires. For toolkits where Composio configures the endpoint, the signing secret is sourced from the connected account's credentials; for toolkits where you configure it, you store the secret on the endpoint yourself.
69 +- **At delivery**, every webhook Composio sends to your endpoint is signed with your subscription secret — verify it as described in [Verifying webhooks](/docs/webhook-verification).
70
71 ## Working with triggers
72
73 <Steps>
74 <Step>
59 -**Configure delivery to your application.** Create a [webhook subscription](/docs/setting-up-triggers/subscribing-to-events) so Composio knows which URL to deliver events to. This is a one-time step per project.
75 +**Configure delivery to your application.** Create a [webhook subscription](/docs/setting-up-triggers/subscribing-to-events) so Composio knows which URL to deliver events to. One-time per project.
76 </Step>
77 <Step>
62 -**Configure ingress (V2 toolkits only).** For toolkits on V2 (currently Slack), [create a webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints) and point the provider's app dashboard at the URL Composio returns. One-time per OAuth app.
78 +**Configure ingress (only when needed).** Use the [schema endpoint](#checking-which-case-applies-to-your-toolkit) to check whether your toolkit needs a manually-configured webhook endpoint; if it does, [create one](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) and point the provider's app dashboard at the URL Composio returns. One-time per OAuth app.
79 </Step>
80 <Step>
65 -**Discover** available trigger types for a toolkit (e.g. `GITHUB_COMMIT_EVENT`).
81 +**Discover** available trigger types for the toolkit (e.g. `GITHUB_COMMIT_EVENT`).
82 </Step>
83 <Step>
84 **Create** an active trigger scoped to a user's connected account — see [Creating triggers](/docs/setting-up-triggers/creating-triggers).
@@ -75,6 +91,15 @@ Composio verifies signatures on both hops:
91 </Step>
92 </Steps>
93
94 +<Accordions>
95 +<Accordion title="What is a trigger type?">
96 +A trigger type is a template that defines what event to listen for and what configuration is required. For example, `GITHUB_COMMIT_EVENT` requires an `owner` and `repo`. Each toolkit exposes its own set of trigger types.
97 +</Accordion>
98 +<Accordion title="What is a trigger instance?">
99 +When you create a trigger from a type, it's scoped to a specific [user and connected account](/docs/users-and-sessions). For example, creating a `GITHUB_COMMIT_EVENT` trigger for user `alice` on the `composio` repo produces a trigger instance with its own `ti_*` ID that you can enable, disable, or delete independently.
100 +</Accordion>
101 +</Accordions>
102 +
103 <Callout>
104 Triggers are scoped to a connected account. If you haven't set up authentication yet, see [Authentication](/docs/authentication).
105 </Callout>
@@ -82,8 +107,7 @@ Triggers are scoped to a connected account. If you haven't set up authentication
107 ## Next steps
108
109 <Cards>
85 - <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />
86 - <Card icon={<RouteIcon />} title="Configuring webhook endpoints" href="/docs/setting-up-triggers/configuring-webhook-endpoints" description="One-time setup for V2 toolkits like Slack: create an ingress URL, store the signing secret, point the provider at it" />
110 + <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Configure the webhook endpoint (when needed), then create trigger instances via the dashboard or SDK" />
111 <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
112 <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
113 <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
docs/content/docs/troubleshooting/triggers.mdx
+6 -4
@@ -14,12 +14,14 @@ Check the error message — the connected account might not have sufficient perm
14 - **Trigger status**: Verify the trigger is enabled, not disabled.
15 - **Logs**: Check the [trigger logs](https://platform.composio.dev?next_page=/logs/triggers) in the dashboard for delivery attempts and errors.
16
17 -## V2 webhook endpoint issues (Slack and other V2 toolkits)
17 +## Webhook endpoint issues (your-own OAuth on Slack, Notion, etc.)
18
19 -- **`400` on every provider request.** The signing secret is missing or wrong on the [webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints). `PATCH` the endpoint with the secret before pointing the provider's dashboard at the URL — Slack auto-disables endpoints after ~36 hours of consecutive failures.
20 -- **`400` on trigger upsert for V2 slugs.** The OAuth app's `client_id` doesn't have a webhook endpoint in this project. Create one via `POST /api/v3.1/webhook_endpoints`.
19 +These only apply when you've configured the webhook endpoint yourself — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint). With Composio-managed OAuth apps, the endpoint is provisioned automatically and these issues don't apply.
20 +
21 +- **`400` on every provider request.** The signing secret on the [webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) is missing or wrong. `PATCH` the endpoint with the secret before pointing the provider's dashboard at the URL — Slack auto-disables endpoints after ~36 hours of consecutive failures.
22 +- **`400` on trigger upsert.** The OAuth app's `client_id` doesn't have a webhook endpoint in this project. Create one via `POST /api/v3.1/webhook_endpoints`.
23 - **`verified_at` is null on the endpoint.** The provider hasn't completed the URL verification handshake yet. Re-save the URL in the provider's dashboard; for Slack, click **Save Changes** on Event Subscriptions.
22 -- **DMs / private channels / reactions don't fire on Slack.** The `app_token` is missing on the endpoint. `PATCH` the endpoint with an `xapp-` token that has the `authorizations:read` scope. See [Configuring webhook endpoints](/docs/setting-up-triggers/configuring-webhook-endpoints) for which Slack triggers require this.
24 +- **DMs / private channels / reactions don't fire on Slack.** The `app_token` is missing on the endpoint. `PATCH` the endpoint with an `xapp-` token that has the `authorizations:read` scope. See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) for which Slack triggers require this.
25 - **Replay-window rejections.** For providers that sign a timestamp (Slack), requests outside the allowed skew window are rejected. Make sure the system posting the events isn't replaying old payloads.
26
27 ## Type errors with trigger payloads
docs/content/docs/webhook-verification.mdx
+10 -9
@@ -7,7 +7,7 @@ keywords: [webhook, verification, signature, HMAC, security]
7 Composio signs every webhook request. Always verify signatures in production to ensure payloads are authentic.
8
9 <Callout>
10 -**Two signatures, two responsibilities.** Composio verifies provider signatures on the **ingress** hop (provider → Composio); you verify Composio's signature on the **delivery** hop (Composio → your endpoint). This page covers the delivery hop. Ingress verification is automatic for V2 endpoints — see [Ingress signature verification (V2)](#ingress-signature-verification-v2) below.
10 +**Two signatures, two responsibilities.** Composio verifies provider signatures on the **ingress** hop (provider → Composio); you verify Composio's signature on the **delivery** hop (Composio → your endpoint). This page covers the delivery hop. Ingress verification happens automatically — see [Ingress signature verification](#ingress-signature-verification) below.
11 </Callout>
12
13 ## SDK verification
@@ -197,28 +197,29 @@ Metadata fields are mixed into the `data` object alongside event data.
197 </Tab>
198 </Tabs>
199
200 -## Ingress signature verification (V2)
200 +## Ingress signature verification
201
202 -For V2 toolkits — currently Slack — Composio verifies the provider's signature against the signing secret stored on the [webhook endpoint](/docs/setting-up-triggers/configuring-webhook-endpoints) **before** any trigger fires. Unsigned or tampered requests are rejected at ingress with `400`, so third parties cannot spoof events onto your triggers.
202 +Composio verifies the provider's signature on every inbound request against the signing secret stored on the [webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) **before** any trigger fires. Unsigned or tampered requests are rejected at ingress with `400`, so third parties cannot spoof events onto your triggers.
203
204 -You don't write any code for this hop — your responsibility is to store the right signing secret on the endpoint:
204 +This hop is automatic — you don't write any code. Your responsibility is just to make sure the signing secret on the endpoint is correct:
205 +
206 +- **Composio-managed OAuth apps** — Composio sources the signing secret from the connected user's credentials; nothing to do.
207 +- **Your own OAuth app on a toolkit that needs manual configuration** (today: Slack, Notion) — `PATCH` the signing secret onto the endpoint as part of [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint):
208
209 ```bash
210 curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
211 -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
212 -H "Content-Type: application/json" \
210 - -d '{ "data": { "webhook_signing_secret": "<YOUR_SLACK_SIGNING_SECRET>" } }'
213 + -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'
214 ```
215
213 -Composio uses the algorithm appropriate for each provider — HMAC-SHA256 for Slack, Ed25519 or shared-token matching for others. For providers that sign a request timestamp (Slack does), replay protection additionally rejects requests outside the allowed skew window.
214 -
215 -V1 ingress URLs (`/api/v3/trigger_instances/{toolkit}/{project_id}/handle`) continue to work as they do today; this section is only relevant for endpoints you've created on V2.
216 +Composio uses the algorithm each provider expects — HMAC-SHA256 for Slack, Ed25519 or shared-token matching for others. For providers that sign a request timestamp (Slack does), replay protection additionally rejects requests outside the allowed skew window.
217
218 ## What to read next
219
220 <Cards>
221 <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Set up webhooks and SDK subscriptions to receive trigger events" />
221 - <Card icon={<RouteIcon />} title="Configuring webhook endpoints" href="/docs/setting-up-triggers/configuring-webhook-endpoints" description="V2 ingress setup: store the provider's signing secret on the endpoint" />
222 + <Card icon={<RouteIcon />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Configure the webhook endpoint when needed and create trigger instances" />
223 <Card icon={<Zap />} title="Triggers overview" href="/docs/triggers" description="How Composio delivers event data from connected apps" />
224 <Card icon={<Key />} title="Connection expiry events" href="/docs/subscribing-to-connection-expiry-events" description="Detect when OAuth connections expire and prompt re-authentication" />
225 </Cards>