Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(triggers): rewrite Configuring section, surface V2 design rationale, slim webhook-verification, drop toolkit FAQ walkthroughs
Anshu Garg6a250d7a531f
diff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdxindex 2134e7f71..ae37d7af4 100644--- a/docs/content/docs/glossary.mdx+++ b/docs/content/docs/glossary.mdx@@ -124,7 +124,7 @@ A specific, active trigger scoped to a user's connected account.</GlossaryTerm><GlossaryTerm name="Webhook Endpoint">-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).+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).</GlossaryTerm><GlossaryTerm name="Webhook Subscription">diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdxindex 24cecad5d..2ac047ce3 100644--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx@@ -12,7 +12,7 @@ Create a trigger to start receiving events. A trigger watches for a specific eve- A [webhook subscription](/docs/setting-up-triggers/subscribing-to-events) on the project, so events have somewhere to land</Callout>-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.+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.## Using the SDK@@ -88,19 +88,23 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses## Configuring the webhook endpoint-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.+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`.-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:+Each OAuth app you bring gets its own ingress URL within a project:```https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event```+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.++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.+<Callout type="warn">-**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.+**Sharing one OAuth app across projects?** Consolidate to a single project or register separate OAuth apps per project before continuing.</Callout>-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.+The steps below use Slack. Other toolkits follow the same flow with different setup fields.### Step 1: Discover what credentials the endpoint needsdiff --git a/docs/content/docs/troubleshooting/triggers.mdx b/docs/content/docs/troubleshooting/triggers.mdxindex 5e30fa99d..7f5f9565f 100644--- a/docs/content/docs/troubleshooting/triggers.mdx+++ b/docs/content/docs/troubleshooting/triggers.mdx@@ -16,7 +16,7 @@ Check the error message — the connected account might not have sufficient perm## Webhook endpoint issues-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.+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.- **`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`.- **`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.diff --git a/docs/content/docs/webhook-verification.mdx b/docs/content/docs/webhook-verification.mdxindex 43d413480..e14f0a6bd 100644--- a/docs/content/docs/webhook-verification.mdx+++ b/docs/content/docs/webhook-verification.mdx@@ -7,7 +7,7 @@ keywords: [webhook, verification, signature, HMAC, security]Composio signs every webhook request. Always verify signatures in production to ensure payloads are authentic.<Callout>-**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.+**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.</Callout>## SDK verification@@ -197,24 +197,6 @@ Metadata fields are mixed into the `data` object alongside event data.</Tab></Tabs>-## Ingress signature verification--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.--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:--- **Composio-managed OAuth apps** — Composio sources the signing secret from the connected user's credentials; nothing to do.-- **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):--```bash-curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'-```--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.-## What to read next<Cards>diff --git a/docs/content/toolkits/faq/notion.md b/docs/content/toolkits/faq/notion.mdindex 98d6f9ec6..38a9faf84 100644--- a/docs/content/toolkits/faq/notion.md+++ b/docs/content/toolkits/faq/notion.md@@ -14,42 +14,4 @@ No. Notion controls access by granting integrations access to specific pages andIt 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.-## How do I set up Notion webhook triggers?--**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.--**If you bring your own Notion integration**, configure a webhook endpoint once per integration. Step-by-step:--1. **Discover what credentials Notion needs.** The schema endpoint is the source of truth for which fields you'll be asked to provide:-- curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=notion" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"--2. **Create the endpoint:**-- curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "toolkit_slug": "notion", "client_id": "<YOUR_NOTION_CLIENT_ID>" }'-- Save the `id` and `webhook_url` from the response.--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).--4. **Store the credentials returned by the schema** (step 1) on the endpoint via `PATCH` — use the field names exactly as they came back:-- curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "data": { "<FIELD_FROM_SCHEMA>": "<VALUE_FROM_NOTION>" } }'--5. **Confirm the endpoint is verified:**-- curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"-- A populated `verified_at` means Notion completed the verification handshake. You can now create Notion triggers on this OAuth app.--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).----diff --git a/docs/content/toolkits/faq/slack.md b/docs/content/toolkits/faq/slack.mdindex 70e347d22..a459819a1 100644--- a/docs/content/toolkits/faq/slack.md+++ b/docs/content/toolkits/faq/slack.md@@ -24,40 +24,7 @@ Update the redirect URL in your Slack App under OAuth & Permissions → Redirect## How do I set up Slack event webhooks?-**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.--**If you bring your own Slack OAuth app**, configure a webhook endpoint once per OAuth app. Step-by-step:--1. **Create the endpoint:**-- curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "toolkit_slug": "slack", "client_id": "<YOUR_SLACK_CLIENT_ID>" }'-- Save the `id` and `webhook_url` from the response.--2. **Store your signing secret on the endpoint** (Slack app → Basic Information → App Credentials → Signing Secret):-- curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'--3. **For DMs, private channels, and reactions, also store an app-level token** (Slack app → Basic Information → App-Level Tokens, scope `authorizations:read`):-- curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{ "data": { "app_token": "xapp-..." } }'--4. **Set Slack app → Event Subscriptions → Request URL** to the `webhook_url` from step 1. Composio responds to Slack's `url_verification` challenge automatically.--5. **Subscribe to the events you need** under Event Subscriptions and save.--If you're using the Slackbot integration, add the bot to the channels you want to monitor.--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).+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).## Why am I getting scope errors on Slack?@@ -69,13 +36,6 @@ For the Slack toolkit, set `as_user=True` to post as the authenticated user. For## Why aren't my Slack triggers working?-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:-- curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"--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.--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.+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.---