@devries-cameron20 / composio Mirror · read-only / commits / 6a250d7a5
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): rewrite Configuring section, surface V2 design rationale, slim webhook-verification, drop toolkit FAQ walkthroughs

Big cleanup pass on the trigger docs. Four threads, one commit. 1. Rewrite "Configuring the webhook endpoint" intro - Drop "Skip this section unless all three are true:" robot speak in favor of reassurance-first ("With Composio-managed OAuth, this is already done for you"). - Drop the (toolkit_slug, project_id, client_id) tuple syntax and the "endpoints are keyed by..." phrasing — internal developer language, not customer-facing. - Surface the V2 design rationale from the changelog: providers accept only one callback URL per OAuth app + each ingress URL routes to one project, so 1 OAuth app = 1 project. Frame the constraint as a trade ("the upside") with the per-project wins from the changelog: isolated ingress rate limits, own signing secret/app-level token, clean fan-out, per-project metering. - Pull the ingress signature verification details into this section as a single paragraph: HMAC-SHA256 / Ed25519 / shared token, replay protection, 400 on tamper. They were on webhook-verification.mdx but belong with the setup material. - Warn callout reduced to action only ("Sharing one OAuth app across projects? Consolidate or register separate apps"). 2. Rename `requires_webhook_endpoint` → `requires_webhook_endpoint_setup` The current name was ambiguous (every webhook trigger goes through a webhook endpoint; what's variable is whether the user sets one up). Adding "_setup" makes the flag's meaning clear. - 4 prose mentions updated: glossary.mdx, creating-triggers.mdx (×1, the second was removed in the rewrite), webhook-verification was removed entirely, troubleshooting/triggers.mdx. 3. Slim webhook-verification.mdx - Drop the "Ingress signature verification" section. The page is about the *delivery* hop signature (you verify Composio's signature on your endpoint) — ingress is automatic and the setup details for it belong on creating-triggers. - Slim the top callout: drop "see Ingress signature verification below" cross-reference (no longer below). 4. Revert toolkit-specific FAQ walkthroughs - slack.md: my five-step Slack walkthrough on "How do I set up Slack event webhooks?" → short pointer to the shared docs. "Why aren't my Slack triggers working?" → short pointer to the troubleshooting page. The shared Configuring section in creating-triggers already mentions Slack-specific dashboard paths (Event Subscriptions → Request URL); duplication on the toolkit page added drift risk. - notion.md: drop the new "How do I set up Notion webhook triggers?" entry I added in a previous pass. Same reasoning — toolkit-specific webhook setup is covered once, on the shared Configuring section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 20:44 UTC 6a250d7a531fdd45fd37c18c6db8fb417a665e86
6 files changed +14 -106
docs/content/docs/glossary.mdx
+1 -1
@@ -124,7 +124,7 @@ A specific, active trigger scoped to a user's connected account.
124 </GlossaryTerm>
125
126 <GlossaryTerm name="Webhook Endpoint">
127 -The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint` flag is true, you configure it yourself once per OAuth app. See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
127 +The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint_setup` flag is true, you configure it yourself once per OAuth app. 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/creating-triggers.mdx
+9 -5
@@ -12,7 +12,7 @@ Create a trigger to start receiving events. A trigger watches for a specific eve
12 - A [webhook subscription](/docs/setting-up-triggers/subscribing-to-events) on the project, so events have somewhere to land
13 </Callout>
14
15 -You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). With Composio-managed OAuth, Composio handles all webhook endpoint setup for you. If you bring your own OAuth app and the trigger type's `requires_webhook_endpoint` flag is true, the create call returns a `400` until you set up the endpoint — see [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below.
15 +You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). With Composio-managed OAuth, Composio handles all webhook endpoint setup for you. If you bring your own OAuth app and the trigger type's `requires_webhook_endpoint_setup` flag is `true`, the create call returns a `400` until you set up the endpoint — see [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below.
16
17 ## Using the SDK
18
@@ -88,19 +88,23 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses
88
89 ## Configuring the webhook endpoint
90
91 -Skip this section unless all three are true: you bring your own OAuth app, the trigger type's `requires_webhook_endpoint` flag is true, and no matching endpoint exists yet (the create call returned a `400`). With Composio-managed OAuth, Composio configures the webhook endpoint for you transparently — none of these steps apply.
91 +Some webhook triggers require a webhook endpoint registered with the provider before they can fire. With Composio-managed OAuth, this is already done for you. You only run the steps below when you bring your own OAuth app and the trigger type's `requires_webhook_endpoint_setup` flag is `true`.
92
93 -A `webhook_endpoint` is 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:
93 +Each OAuth app you bring gets its own ingress URL within a project:
94
95 ```
96 https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
97 ```
98
99 +A single OAuth app can serve at most one Composio project, since providers accept only one callback URL per OAuth app and each ingress URL routes to a single project. The upside: every project becomes its own webhook tenant with isolated ingress rate limits, its own signing secret and app-level token, clean fan-out (events only reach that project's triggers), and per-project metering.
100 +
101 +Provider events are verified at ingress against the endpoint's signing secret before any trigger fires — HMAC-SHA256 for Slack, Ed25519 or shared-token matching for others. For providers that sign a request timestamp, replay protection additionally rejects requests outside the allowed skew window. Unsigned or tampered requests get a `400` at ingress, so third parties cannot spoof events onto your triggers.
102 +
103 <Callout type="warn">
100 -**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.
104 +**Sharing one OAuth app across projects?** Consolidate to a single project or register separate OAuth apps per project before continuing.
105 </Callout>
106
103 -The walkthrough below uses Slack as the example. Substitute the toolkit slug for any other toolkit on the same flow — the API surface is identical.
107 +The steps below use Slack. Other toolkits follow the same flow with different setup fields.
108
109 ### Step 1: Discover what credentials the endpoint needs
110
docs/content/docs/troubleshooting/triggers.mdx
+1 -1
@@ -16,7 +16,7 @@ Check the error message — the connected account might not have sufficient perm
16
17 ## Webhook endpoint issues
18
19 -These only apply to triggers whose `requires_webhook_endpoint` flag is true — 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, so these don't apply.
19 +These only apply to triggers whose `requires_webhook_endpoint_setup` flag is `true` — 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, so these don't apply.
20
21 - **`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`.
22 - **`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.
docs/content/docs/webhook-verification.mdx
+1 -19
@@ -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 happens automatically — see [Ingress signature verification](#ingress-signature-verification) below.
10 +**Two signatures, two responsibilities.** Composio verifies provider signatures on the **ingress** hop automatically. You verify Composio's signature on the **delivery** hop — this page covers that.
11 </Callout>
12
13 ## SDK verification
@@ -197,24 +197,6 @@ Metadata fields are mixed into the `data` object alongside event data.
197 </Tab>
198 </Tabs>
199
200 -## Ingress signature verification
201 -
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 -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 trigger whose `requires_webhook_endpoint` flag is true** — `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" \
213 - -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'
214 -```
215 -
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 -
200 ## What to read next
201
202 <Cards>
docs/content/toolkits/faq/notion.md
-38
@@ -14,42 +14,4 @@ No. Notion controls access by granting integrations access to specific pages and
14
15 It depends on the integration type. OAuth apps (public) let users select which pages to share during authorization. Internal integrations (API key) have page access managed in the integration settings.
16
17 -## How do I set up Notion webhook triggers?
18 -
19 -**If you use Composio-managed Notion credentials**, nothing to set up — the webhook endpoint is already provisioned for your project. Create the trigger and you're done.
20 -
21 -**If you bring your own Notion integration**, configure a webhook endpoint once per integration. Step-by-step:
22 -
23 -1. **Discover what credentials Notion needs.** The schema endpoint is the source of truth for which fields you'll be asked to provide:
24 -
25 - curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=notion" \
26 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
27 -
28 -2. **Create the endpoint:**
29 -
30 - curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
31 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
32 - -H "Content-Type: application/json" \
33 - -d '{ "toolkit_slug": "notion", "client_id": "<YOUR_NOTION_CLIENT_ID>" }'
34 -
35 - Save the `id` and `webhook_url` from the response.
36 -
37 -3. **Add the `webhook_url`** from step 2 to your Notion integration's **Webhooks** settings (in the integration's configuration page on Notion's developer dashboard).
38 -
39 -4. **Store the credentials returned by the schema** (step 1) on the endpoint via `PATCH` — use the field names exactly as they came back:
40 -
41 - curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
42 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
43 - -H "Content-Type: application/json" \
44 - -d '{ "data": { "<FIELD_FROM_SCHEMA>": "<VALUE_FROM_NOTION>" } }'
45 -
46 -5. **Confirm the endpoint is verified:**
47 -
48 - curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
49 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
50 -
51 - A populated `verified_at` means Notion completed the verification handshake. You can now create Notion triggers on this OAuth app.
52 -
53 -For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
54 -
17 ---
docs/content/toolkits/faq/slack.md
+2 -42
@@ -24,40 +24,7 @@ Update the redirect URL in your Slack App under OAuth & Permissions → Redirect
24
25 ## How do I set up Slack event webhooks?
26
27 -**If you use Composio-managed Slack credentials**, nothing to set up — the webhook endpoint is already provisioned for your project. Create the trigger and you're done.
28 -
29 -**If you bring your own Slack OAuth app**, configure a webhook endpoint once per OAuth app. Step-by-step:
30 -
31 -1. **Create the endpoint:**
32 -
33 - curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
34 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
35 - -H "Content-Type: application/json" \
36 - -d '{ "toolkit_slug": "slack", "client_id": "<YOUR_SLACK_CLIENT_ID>" }'
37 -
38 - Save the `id` and `webhook_url` from the response.
39 -
40 -2. **Store your signing secret on the endpoint** (Slack app → Basic Information → App Credentials → Signing Secret):
41 -
42 - curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
43 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
44 - -H "Content-Type: application/json" \
45 - -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'
46 -
47 -3. **For DMs, private channels, and reactions, also store an app-level token** (Slack app → Basic Information → App-Level Tokens, scope `authorizations:read`):
48 -
49 - curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
50 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
51 - -H "Content-Type: application/json" \
52 - -d '{ "data": { "app_token": "xapp-..." } }'
53 -
54 -4. **Set Slack app → Event Subscriptions → Request URL** to the `webhook_url` from step 1. Composio responds to Slack's `url_verification` challenge automatically.
55 -
56 -5. **Subscribe to the events you need** under Event Subscriptions and save.
57 -
58 -If you're using the Slackbot integration, add the bot to the channels you want to monitor.
59 -
60 -For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
27 +With Composio-managed Slack credentials, the webhook endpoint is already provisioned — just create the trigger. If you bring your own Slack OAuth app, see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
28
29 ## Why am I getting scope errors on Slack?
30
@@ -69,13 +36,6 @@ For the Slack toolkit, set `as_user=True` to post as the authenticated user. For
36
37 ## Why aren't my Slack triggers working?
38
72 -If you bring your own Slack OAuth app, the most common cause is a missing or wrong **signing secret on the webhook endpoint** — every inbound request fails signature verification with `400`, and Slack auto-disables the URL after about 36 hours of consecutive failures. Confirm the endpoint is set up correctly:
73 -
74 - curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
75 - -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
76 -
77 -Look for an endpoint with your `client_id` and a populated `verified_at`. If `verified_at` is null, the URL hasn't completed Slack's `url_verification` handshake yet — re-save the URL on Slack app → Event Subscriptions. If you don't see an endpoint at all, follow [How do I set up Slack event webhooks?](#how-do-i-set-up-slack-event-webhooks) above.
78 -
79 -For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
39 +See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the common failure modes — signing secret missing, `verified_at` null, missing app-level token, and replay-window rejections.
40
41 ---