@devries-cameron20 / composio-1 / commits / 916894fbc
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): trim concept page; keep configuring section in creating-triggers

Iteration based on review of the rendered preview. triggers.mdx - Webhook row: add "processes the payload" to the description so the table reflects what Composio does between signature verification and fan-out. - Drop the "Setup at a glance" 4-column table and the second flag-vs-OAuth-source table — both restated content already covered by the bullets and the steps below. - End-to-end flow: keep the arrow + the two URL bullets as a slim description; webhook-endpoint bullet links to the section in creating-triggers (not a standalone page). - Drop the "Two webhook URLs" duplicate table inside End-to-end flow. - "Working with triggers" steps already lead with subscription before create — no change. - Next-steps cards reordered: Subscribing first (one-time per project), then Creating, then the situational Configuring the webhook endpoint card linking to the section anchor inside Creating triggers. creating-triggers.mdx - Restore the "Configuring the webhook endpoint" section (5 steps + Updating subsection) as a section, not a separate page. Earlier iteration tried a standalone page; reverted per direction (customers should hit a short note in triggers.mdx and follow it to a section in creating-triggers). - Remove the in-page configuring page link from the next-steps cards; reuse the slot for "Subscribing to events". - Prereq callout adds: webhook subscription must exist on the project so events have somewhere to land. Cross-references in subscribing-to-events.mdx, webhook-verification.mdx, troubleshooting/triggers.mdx, glossary.mdx, slack/notion FAQs all already point at creating-triggers#configuring-the-webhook-endpoint — no further change needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 19:02 UTC 916894fbc0ad754df125d270deb489d65ce068ab
2 files changed +15 -30
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+6 -5
@@ -1,7 +1,7 @@
1 ---
2 title: Creating triggers
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]
3 +description: Inspect a trigger type and create the instance via the SDK or the dashboard
4 +keywords: [triggers, create trigger, trigger config]
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).
@@ -9,9 +9,10 @@ Create a trigger to start receiving events. A trigger watches for a specific eve
9 <Callout type="info" title="Prerequisites">
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
12 +- A [webhook subscription](/docs/setting-up-triggers/subscribing-to-events) on the project, so events have somewhere to land
13 </Callout>
14
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 +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.
16
17 ## Using the SDK
18
@@ -87,7 +88,7 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses
88
89 ## Configuring the webhook endpoint
90
90 -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.
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.
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:
94
@@ -245,7 +246,7 @@ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
246 ## What to read next
247
248 <Cards>
248 - <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
249 + <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Set up the webhook subscription URL Composio delivers events to" />
250 <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures so you know payloads came from Composio" />
251 <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
252 </Cards>
docs/content/docs/triggers.mdx
+9 -25
@@ -12,38 +12,21 @@ When events occur in apps — a new Slack message, a GitHub commit, an incoming
12
13 | Type | What happens | Examples |
14 |---|---|---|
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 -## Setup at a glance
21 -
22 -Two pieces of setup, both one-time:
23 -
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 -
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 -
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.
15 +| **Webhook** | The provider pushes events to a Composio-issued ingress URL in real time. Composio verifies the provider's signature, processes the payload, and fans the event out to matching trigger instances. | Slack, 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, Google Calendar |
17
18 ## End-to-end flow
19
20 For every webhook trigger, an event takes the same path on the way to your application:
21
22 ```
38 -provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpoint
23 +provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your application
24 ```
25
41 -Two webhook URLs sit on opposite sides of Composio. Don't confuse them:
26 +Two URLs sit on opposite sides of Composio, both configured once:
27
43 -| URL | Direction | Who configures it |
44 -|---|---|---|
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) |
28 +- **Webhook subscription** — your URL where Composio delivers signed events. One per project. See [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events).
29 +- **Webhook endpoint** — the ingress URL the provider posts events to. Composio configures this for you in most cases; for some webhook triggers, you may need to set it up once per OAuth app — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) on the Creating triggers page.
30
31 Composio verifies signatures on both hops:
32
@@ -89,8 +72,9 @@ Triggers are scoped to a connected account. If you haven't set up authentication
72 ## Next steps
73
74 <Cards>
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" />
75 + <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="One-time per project: tell Composio which URL to deliver events to" />
76 + <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Inspect a trigger type and create trigger instances via the SDK or dashboard" />
77 + <Card icon={<RouteIcon />} title="Configuring the webhook endpoint" href="/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint" description="Situational: required only when you bring your own OAuth app and the trigger needs it" />
78 <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
79 <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
80 <Card icon={<BookOpen />} title="Example: Gmail labeler" href="/cookbooks/gmail-labeler" description="Build an automated email labeling agent using triggers" />