@devries-cameron20 / composio-1 / commits / 56de32c57
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.

docs(triggers): pivot discovery to trigger-level requires_webhook_endpoint flag

Rethought the structure: whether endpoint configuration is required is a property of the trigger type, not of (toolkit + OAuth source). So: - The trigger type exposes a `requires_webhook_endpoint` flag (forthcoming on the SDK / API per product direction). - The reader inspects the trigger type. If the flag is true, configure the endpoint; otherwise just create. - The toolkit-level schema endpoint is no longer a primary upfront check — it's used inside the configuration walkthrough as the source of truth for which fields to PATCH. triggers.mdx - Drop the "Webhook endpoints" subsection with the two-row Composio- configures vs you-configure table. - Drop the "Checking which case applies to your toolkit" subsection with the schema-endpoint upfront check. - Add a "Setup at a glance" table — webhook subscription always (per project), webhook endpoint only when required (per OAuth app), determined at the trigger level. - Working-with-triggers steps now lead with "Pick a trigger type and inspect it" before the create step. creating-triggers.mdx - Reorder so the SDK and dashboard sections come first (most readers' path) and the 5-step "Configuring the webhook endpoint" walkthrough is last, gated behind "skip unless your trigger needs it." - Code samples now print `requires_webhook_endpoint` / `requiresWebhookEndpoint` alongside `config`, so readers see the discovery moment in the same snippet. - Walkthrough body unchanged — still discovers fields via the schema endpoint, creates, PATCHes credentials, points provider at URL, confirms verified_at. subscribing-to-events.mdx - Top callout reframed around the flag instead of toolkit names. webhook-verification.mdx - Ingress section's "your own OAuth app on a toolkit (today: Slack, Notion)" bullet reframed around the flag. troubleshooting/triggers.mdx - Section header drops the toolkit-name list. - Lead-in note now references the flag, not "if you've configured the webhook endpoint yourself." glossary.mdx - Webhook Endpoint entry rephrased around the flag. Toolkit FAQs (slack.md, notion.md) and meta.json unchanged — toolkit- specific FAQs naturally talk per-toolkit, and the flag-vs-toolkit framing doesn't change the steps users follow there. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 18:28 UTC 56de32c579c4f4a7258c17962b8795430c6e2712
6 files changed +122 -137
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 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).
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).
128 </GlossaryTerm>
129
130 <GlossaryTerm name="Webhook Subscription">
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+100 -97
@@ -1,39 +1,122 @@
1 ---
2 title: Creating triggers
3 -description: Configure the webhook endpoint when needed, then create trigger instances via the dashboard or SDK
3 +description: Inspect a trigger type, create the instance, and configure the webhook endpoint when required
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).
8
9 <Callout type="info" title="Prerequisites">
10 -Before creating triggers, ensure you have:
10 - An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
11 - A connected account for the user whose events you want to capture
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.
12 </Callout>
13
16 -## Configuring the webhook endpoint
14 +You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). If the trigger type's `requires_webhook_endpoint` flag is true and you haven't configured an endpoint yet, the create call returns a `400` — follow [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) and retry.
15 +
16 +## Using the SDK
17 +
18 +Before creating a trigger, inspect the trigger type. The response tells you what config it requires and whether you need to set up a webhook endpoint first.
19 +
20 +<Callout>
21 +When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.
22 +</Callout>
23 +
24 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
25 + <Tab value="Python">
26 +```python
27 +from composio import Composio
28 +
29 +composio = Composio()
30 +user_id = "user-id-123435"
31 +
32 +# Inspect the trigger type
33 +trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
34 +print(trigger_type.config)
35 +# {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
36 +print(trigger_type.requires_webhook_endpoint)
37 +# False → create the trigger normally
38 +# True → see "Configuring the webhook endpoint" below first
39 +
40 +# Create trigger with the required config
41 +trigger = composio.triggers.create(
42 + slug="GITHUB_COMMIT_EVENT",
43 + user_id=user_id,
44 + trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
45 +)
46 +print(f"Trigger created: {trigger.trigger_id}")
47 +```
48 + </Tab>
49 + <Tab value="TypeScript">
50 +```typescript
51 +import { Composio } from '@composio/core';
52 +
53 +const composio = new Composio();
54 +const userId = 'user-id-123435';
55 +
56 +// Inspect the trigger type
57 +const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
58 +console.log(triggerType.config);
59 +// {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
60 +console.log(triggerType.requiresWebhookEndpoint);
61 +// false → create the trigger normally
62 +// true → see "Configuring the webhook endpoint" below first
63
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.
64 +// Create trigger with the required config
65 +const trigger = await composio.triggers.create(
66 + userId,
67 + 'GITHUB_COMMIT_EVENT',
68 + {
69 + triggerConfig: {
70 + owner: 'your-repo-owner',
71 + repo: 'your-repo-name'
72 + }
73 + }
74 +);
75 +console.log(`Trigger created: ${trigger.triggerId}`);
76 +```
77 + </Tab>
78 +</Tabs>
79
80 <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).
81 +Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
82 </Callout>
83
24 -### Step 1: Discover whether you need to configure anything
84 +## Using the dashboard
85 +
86 +1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
87 +2. Navigate to **Active Triggers** and click **Create Trigger**
88 +3. Select the connected account for which you want to create a trigger
89 +4. Choose a trigger type and fill in the required configuration. If the trigger requires a webhook endpoint, the dashboard prompts you to configure one before saving.
90 +5. Click **Create Trigger**
91 +
92 +<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
93 +
94 +## Configuring the webhook endpoint
95 +
96 +Skip this section unless you already know you need it — the trigger type's `requires_webhook_endpoint` flag was true, or the create call returned a `400` saying a webhook endpoint must be configured.
97 +
98 +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:
99 +
100 +```
101 +https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
102 +```
103 +
104 +<Callout type="warn">
105 +**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.
106 +</Callout>
107 +
108 +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.
109 +
110 +### Step 1: Discover what credentials the endpoint needs
111
26 -Call the schema endpoint for your toolkit. The response is the source of truth.
112 +Call the schema endpoint for the toolkit. The `setup_fields` in the response tell you exactly what to collect from the provider's app dashboard.
113
114 ```bash
29 -curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug={toolkit_slug}" \
115 +curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
116 -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
117 ```
118
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:
119 +Sample response:
120
121 ```json
122 {
@@ -82,13 +165,9 @@ Sample response:
165
166 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.
167
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 -
168 ### Step 3: Store the credentials returned by the schema
169
91 -`PATCH` each field returned by the schema endpoint. For Slack, that's the signing secret and (when applicable) the app-level token.
170 +`PATCH` each field returned by the schema. For Slack, that's the signing secret and (when applicable) the app-level token.
171
172 ```bash
173 curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
@@ -122,10 +201,6 @@ curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT
201
202 Generate the Slack app-level token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
203
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 -
204 ### Step 4: Point the provider's app dashboard at the URL
205
206 Paste the `webhook_url` from step 2 into the provider's app dashboard:
@@ -142,7 +217,7 @@ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
217 -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
218 ```
219
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.
220 +A populated `verified_at` timestamp on the response means the provider has completed the handshake. You can now retry the trigger creation call from [Using the SDK](#using-the-sdk).
221
222 ### Updating an endpoint
223
@@ -164,87 +239,15 @@ curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_
239 -d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>", "app_token": "<NEW_APP_TOKEN>" } }'
240 ```
241
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.
242 +The `webhook_url` 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.
243
169 -To list every endpoint in the current project (useful when operating across many OAuth apps):
244 +To list every endpoint in the current project:
245
246 ```bash
247 curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
248 -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
249 ```
250
176 -## Using the SDK
177 -
178 -Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
179 -
180 -<Callout>
181 -When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.
182 -</Callout>
183 -
184 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
185 - <Tab value="Python">
186 -```python
187 -from composio import Composio
188 -
189 -composio = Composio()
190 -user_id = "user-id-123435"
191 -
192 -# Check what configuration is required
193 -trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
194 -print(trigger_type.config)
195 -# Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
196 -
197 -# Create trigger with the required config
198 -trigger = composio.triggers.create(
199 - slug="GITHUB_COMMIT_EVENT",
200 - user_id=user_id,
201 - trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
202 -)
203 -print(f"Trigger created: {trigger.trigger_id}")
204 -```
205 - </Tab>
206 - <Tab value="TypeScript">
207 -```typescript
208 -import { Composio } from '@composio/core';
209 -
210 -const composio = new Composio();
211 -const userId = 'user-id-123435';
212 -
213 -// Check what configuration is required
214 -const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
215 -console.log(triggerType.config);
216 -// Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
217 -
218 -// Create trigger with the required config
219 -const trigger = await composio.triggers.create(
220 - userId,
221 - 'GITHUB_COMMIT_EVENT',
222 - {
223 - triggerConfig: {
224 - owner: 'your-repo-owner',
225 - repo: 'your-repo-name'
226 - }
227 - }
228 -);
229 -console.log(`Trigger created: ${trigger.triggerId}`);
230 -```
231 - </Tab>
232 -</Tabs>
233 -
234 -<Callout>
235 -Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
236 -</Callout>
237 -
238 -## Using the dashboard
239 -
240 -1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
241 -2. Navigate to **Active Triggers** and click **Create Trigger**
242 -3. Select the connected account for which you want to create a trigger
243 -4. Choose a trigger type and fill in the required configuration
244 -5. Click **Create Trigger**
245 -
246 -<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
247 -
251 ## What to read next
252
253 <Cards>
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).** 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.
10 +- **Provider → Composio (ingress).** A webhook endpoint per OAuth app — Composio configures it for you in most cases. If a trigger type's `requires_webhook_endpoint` flag is true, you [configure the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) once per OAuth app before creating the trigger.
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
+16 -34
@@ -4,7 +4,7 @@ description: Understand how Composio delivers event data from connected apps
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.
7 +When events occur in apps — a new Slack message, a GitHub commit, 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
@@ -12,41 +12,23 @@ When events occur in apps, like a new Slack message, a GitHub commit, or an inco
12
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, ... |
15 +| **Webhook** | The provider pushes 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
20 +## Setup at a glance
21
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:
22 +Two pieces of setup, both one-time:
23
24 -```
25 -https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
26 -```
27 -
28 -An endpoint is configured in one of two ways:
24 +| Piece | When it's needed | Scope | Where it's documented |
25 +|---|---|---|---|
26 +| **Webhook subscription** — your URL where Composio delivers signed events | Always | Once per project | [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
27 +| **Webhook endpoint** — the URL the provider posts events to | Only when the trigger type requires it | Once per OAuth app | [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) |
28
30 -| Configuration | When it applies | What you do |
31 -|---|---|---|
32 -| **Composio configures it for you** | You're using a Composio-managed OAuth app, or your own OAuth app on a toolkit where Composio can register webhooks on your behalf using the connected user's credentials (e.g. **Asana**) | Nothing. Composio handles endpoint setup, signature verification, and provider-side registration when you create the trigger. |
33 -| **You configure it** | You're using your own OAuth app on a toolkit where the provider posts events at the OAuth-app level — today **Slack** and **Notion**, with more toolkits moving to this flow over time | Set up the webhook endpoint once per OAuth app before you create any triggers — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint). |
34 -
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 -```
29 +Whether a webhook endpoint needs to be configured is a property of the trigger type itself — `composio.triggers.get_type()` exposes a `requires_webhook_endpoint` flag, and the trigger creation call returns a `400` if the flag is true and no endpoint exists yet.
30
48 -- **`setup_fields` is empty or absent** → 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, and so on. Today this applies to **Slack** and **Notion**; more toolkits will adopt this flow over time.
31 +For Composio-managed OAuth apps the flag is always false — endpoints are pre-provisioned and you never configure them. With your own OAuth app it depends on the trigger.
32
33 ## End-to-end flow
34
@@ -60,7 +42,7 @@ Two webhook URLs sit on opposite sides of Composio. Don't confuse them:
42
43 | URL | Direction | Who configures it |
44 |---|---|---|
63 -| **Ingress** (`/api/v3.1/webhook_ingress/...`) | Provider → Composio | Composio in most cases; you when you bring your own OAuth app on a toolkit like Slack or Notion — see [Webhook endpoints](#webhook-endpoints) above |
45 +| **Ingress** (`/api/v3.1/webhook_ingress/...`) | Provider → Composio | Composio in most cases; you when the trigger type's `requires_webhook_endpoint` flag is true — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) |
46 | **Webhook subscription** (your URL) | Composio → your application | You, once per project — see [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
47
48 Composio verifies signatures on both hops:
@@ -75,16 +57,16 @@ Composio verifies signatures on both hops:
57 **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.
58 </Step>
59 <Step>
78 -**Configure ingress, only if your toolkit needs it.** Use the [schema endpoint](#checking-which-case-applies-to-your-toolkit) to check. If it returns setup fields, [create the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) and paste the URL Composio returns into the provider's app dashboard. One-time per OAuth app.
60 +**Pick a trigger type and inspect it.** Find the trigger type for the event you want (e.g. `GITHUB_COMMIT_EVENT`) and inspect it — the response tells you what config it needs and whether a webhook endpoint must be configured first.
61 </Step>
62 <Step>
81 -**Discover** available trigger types for the toolkit (e.g. `GITHUB_COMMIT_EVENT`).
63 +**If the trigger requires a webhook endpoint, configure it.** Follow [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint). One-time per OAuth app.
64 </Step>
65 <Step>
84 -**Create** an active trigger scoped to a user's connected account — see [Creating triggers](/docs/setting-up-triggers/creating-triggers).
66 +**Create the trigger** scoped to a user's connected account — see [Creating triggers](/docs/setting-up-triggers/creating-triggers).
67 </Step>
68 <Step>
87 -**Receive events** at your webhook subscription URL, [verify the signature](/docs/webhook-verification), and route on `metadata.trigger_slug`.
69 +**Receive events** at your subscription URL, [verify the signature](/docs/webhook-verification), and route on `metadata.trigger_slug`.
70 </Step>
71 <Step>
72 **Manage** triggers as needed — see [Managing triggers](/docs/setting-up-triggers/managing-triggers).
@@ -107,7 +89,7 @@ Triggers are scoped to a connected account. If you haven't set up authentication
89 ## Next steps
90
91 <Cards>
110 - <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Configure the webhook endpoint if your toolkit needs it, then create trigger instances via the dashboard or SDK" />
92 + <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Inspect a trigger type, configure the webhook endpoint when required, then create trigger instances" />
93 <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
94 <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
95 <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
+3 -3
@@ -14,12 +14,12 @@ 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 -## Webhook endpoint issues (your-own OAuth on Slack, Notion, etc.)
17 +## Webhook endpoint issues
18
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.
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.
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.
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.
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.
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.
docs/content/docs/webhook-verification.mdx
+1 -1
@@ -204,7 +204,7 @@ Composio verifies the provider's signature on every inbound request against the
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):
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>" \