@devries-cameron20 / composio Mirror · read-only / commits / d195f460a
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, 22:15 UTC

docs(triggers): introduce webhook endpoints and three delivery models

Trigger docs predate Webhook Triggers V2 — they describe a single "webhook trigger" model in which Composio handles ingress automatically. That story is no longer complete: V2 toolkits (Slack today, more to follow) require a one-time, project-level setup where the user registers an OAuth app's signing secret on a webhook_endpoint and points the provider's app dashboard at a Composio-issued URL. This change rewrites the trigger surface around three delivery models: - Polling — Composio polls the provider on a schedule (e.g. Gmail). - User-level webhook — Composio auto-registers a per-user webhook with the provider on trigger creation (Asana, GitHub, Outlook, ...). - App-level webhook endpoint (V2) — the user creates a webhook_endpoint per OAuth app, stores the provider's signing secret, and points the provider at the issued ingress URL (Slack). Files: - triggers.mdx — overview rewritten around the three delivery models, end-to-end flow with both webhook URLs (ingress vs subscription), and ingress-side signature verification. - setting-up-triggers/configuring-webhook-endpoints.mdx — new page, full V2 walkthrough (Slack) using Steps: discover schema → create endpoint → store signing secret → optionally add app token → point provider at URL → confirm verified_at. Also covers PATCH vs POST update semantics and V1 → V2 migration triggers. - setting-up-triggers/creating-triggers.mdx — note V2 prerequisite in the prerequisites callout; link to new page in next steps. - setting-up-triggers/subscribing-to-events.mdx — top-of-page callout disambiguating the two webhook URLs (ingress vs subscription). - setting-up-triggers/meta.json — register new page, ordered after creating-triggers. - webhook-verification.mdx — split responsibility callout at the top (Composio verifies ingress, you verify delivery); add an "Ingress signature verification (V2)" section. - troubleshooting/triggers.mdx — V2-specific failure modes (signing-secret missing, verified_at null, missing app_token, replay-window rejections). - glossary.mdx — "Trigger" entry rewritten around three models; new "Webhook Endpoint" and "Webhook Subscription" entries. Note: the corresponding webhook_endpoints API reference pages are auto-generated from Apollo's OpenAPI export by the docs-update-data workflow. They are already present on PR #3238 (the open auto-update-data PR) and will surface in the API reference the moment that PR merges. Separately: GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=... is referenced in the changelog and on the new doc page but is not in Apollo's exported OpenAPI spec. That's an Apollo annotation gap to fix on the backend side; it does not block this docs PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 13:54 UTC d195f460ac02c320a6c2b1a5654831d8ac61d50e
8 files changed +331 -23
docs/content/docs/glossary.mdx
+9 -1
@@ -116,13 +116,21 @@ 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. Two delivery types: **webhook** (the app pushes events in real time, e.g. GitHub, Slack) and **polling** (Composio periodically checks for new data, e.g. Gmail). See [Triggers](/docs/triggers).
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).
120 </GlossaryTerm>
121
122 <GlossaryTerm name="Trigger Instance">
123 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).
128 +</GlossaryTerm>
129 +
130 +<GlossaryTerm name="Webhook Subscription">
131 +The URL Composio delivers signed events to in your application. One per project, configured via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks). See [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events).
132 +</GlossaryTerm>
133 +
134 <GlossaryTerm name="User ID">
135 An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between user IDs. See [Users and sessions](/docs/users-and-sessions).
136 </GlossaryTerm>
docs/content/docs/setting-up-triggers/configuring-webhook-endpoints.mdx new
+214
@@ -0,0 +1,214 @@
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
+4 -2
@@ -10,6 +10,7 @@ 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.
14 </Callout>
15
16 You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard).
@@ -89,6 +90,7 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses
90 ## What to read next
91
92 <Cards>
92 - <Card icon={<Zap />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
93 - <Card icon={<Zap />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
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" />
94 + <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
95 + <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
96 </Cards>
docs/content/docs/setting-up-triggers/meta.json
+1
@@ -2,6 +2,7 @@
2 "title": "Using Triggers",
3 "pages": [
4 "creating-triggers",
5 + "configuring-webhook-endpoints",
6 "subscribing-to-events",
7 "managing-triggers"
8 ]
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+7
@@ -4,6 +4,13 @@ description: Receive trigger events via webhooks or SDK subscriptions
4 keywords: [webhooks, subscribe, events, webhook payload, V3]
5 ---
6
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.
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 +
14 ## Webhooks
15
16 Webhooks are the recommended way to receive trigger events in production. To start receiving events, create a webhook subscription with your endpoint URL and select which event types you want to receive. You can subscribe to any combination:
docs/content/docs/triggers.mdx
+64 -18
@@ -1,35 +1,80 @@
1 ---
2 title: Triggers
3 description: Understand how Composio delivers event data from connected apps
4 -keywords: [triggers, webhooks, events, polling, concepts]
4 +keywords: [triggers, webhooks, events, polling, webhook endpoints, 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 -There are two delivery types:
11 +## Three delivery models
12
13 -- **Webhook triggers**: Apps like GitHub and Slack push events to Composio in real time. When an event fires, Composio forwards the payload to your webhook endpoint.
14 -- **Polling triggers**: For apps that don't support outgoing webhooks (e.g., Gmail), Composio polls for new data on a schedule. For Composio managed auth, polling intervals have a minimum of 15 minutes. Expect delays between the source event and delivery.
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.
14
16 -## Working with triggers
17 -
18 -1. **Configure** your webhook endpoint so Composio knows where to deliver events
19 -2. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
20 -3. **Create** an active trigger scoped to a user's connected account
21 -4. **Receive events**: Composio sends payloads to your endpoint
22 -5. **Manage**: enable, disable, or delete triggers as needed
15 +| Delivery model | What Composio does | What you do |
16 +|---|---|---|
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 |
20
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>
28 -<Accordion title="What happens when you create an active trigger?">
29 -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 with its own ID.
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>
34
35 +## End-to-end flow
36 +
37 +For every trigger, regardless of delivery model, events take the same path on the way to your application:
38 +
39 +```
40 +provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpoint
41 +```
42 +
43 +Two webhook URLs sit on opposite sides of Composio. Don't confuse them:
44 +
45 +| URL | Direction | Who configures it |
46 +|---|---|---|
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)) |
48 +| **Webhook subscription** (your URL) | Composio → your application | You, once per project — see [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
49 +
50 +Composio verifies signatures on both hops:
51 +
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).
54 +
55 +## Working with triggers
56 +
57 +<Steps>
58 +<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.
60 +</Step>
61 +<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.
63 +</Step>
64 +<Step>
65 +**Discover** available trigger types for a toolkit (e.g. `GITHUB_COMMIT_EVENT`).
66 +</Step>
67 +<Step>
68 +**Create** an active trigger scoped to a user's connected account — see [Creating triggers](/docs/setting-up-triggers/creating-triggers).
69 +</Step>
70 +<Step>
71 +**Receive events** at your webhook subscription URL, [verify the signature](/docs/webhook-verification), and route on `metadata.trigger_slug`.
72 +</Step>
73 +<Step>
74 +**Manage** triggers as needed — see [Managing triggers](/docs/setting-up-triggers/managing-triggers).
75 +</Step>
76 +</Steps>
77 +
78 <Callout>
79 Triggers are scoped to a connected account. If you haven't set up authentication yet, see [Authentication](/docs/authentication).
80 </Callout>
@@ -37,9 +82,10 @@ Triggers are scoped to a connected account. If you haven't set up authentication
82 ## Next steps
83
84 <Cards>
40 - <Card title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />
41 - <Card title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
42 - <Card title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
43 - <Card title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
44 - <Card title="Example: Gmail labeler" href="/cookbooks/gmail-labeler" description="Build an automated email labeling agent using triggers" />
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" />
87 + <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
88 + <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
89 + <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
90 + <Card icon={<BookOpen />} title="Example: Gmail labeler" href="/cookbooks/gmail-labeler" description="Build an automated email labeling agent using triggers" />
91 </Cards>
docs/content/docs/troubleshooting/triggers.mdx
+8
@@ -14,6 +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)
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`.
21 +- **`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.
23 +- **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.
24 +
25 ## Type errors with trigger payloads
26
27 Use `getType()` / `get_type()` to inspect the exact payload schema for a trigger type. This shows you the fields and types you should expect.
docs/content/docs/webhook-verification.mdx
+24 -2
@@ -6,6 +6,10 @@ keywords: [webhook, verification, signature, HMAC, security]
6
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.
11 +</Callout>
12 +
13 ## SDK verification
14
15 The SDK handles signature verification, payload parsing, and version detection (V1, V2, V3).
@@ -193,11 +197,29 @@ Metadata fields are mixed into the `data` object alongside event data.
197 </Tab>
198 </Tabs>
199
200 +## Ingress signature verification (V2)
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.
203 +
204 +You don't write any code for this hop — your responsibility is to store the right signing secret on the endpoint:
205 +
206 +```bash
207 +curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
208 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
209 + -H "Content-Type: application/json" \
210 + -d '{ "data": { "webhook_signing_secret": "<YOUR_SLACK_SIGNING_SECRET>" } }'
211 +```
212 +
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 +
217 ## What to read next
218
219 <Cards>
199 - <Card icon={<Zap />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Set up webhooks and SDK subscriptions to receive trigger events" />
220 + <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={<Zap />} title="Triggers overview" href="/docs/triggers" description="How Composio delivers event data from connected apps" />
201 - <Card icon={<Zap />} title="Connection expiry events" href="/docs/subscribing-to-connection-expiry-events" description="Detect when OAuth connections expire and prompt re-authentication" />
223 + <Card icon={<Key />} title="Connection expiry events" href="/docs/subscribing-to-connection-expiry-events" description="Detect when OAuth connections expire and prompt re-authentication" />
224 </Cards>
225