@devries-cameron20 / composio-1 / commits / 5aa9430d7
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): slim concept page to orientation only; keep concepts unmixed per page

Per review: - triggers.mdx feels duplicative when it both summarizes setup and links to workflow pages that cover the same. - subscribing-to-events.mdx introduces "webhook endpoints" in a callout, which mixes two distinct concepts on a page that should only own the subscription side. triggers.mdx - "Two delivery types" renamed to "Two trigger types". - Drop the trailing "..." in webhook examples; remove GitHub. - Add "Google Calendar" to polling examples. - Add "processes the payload" to the Webhook row description. - Drop the "End-to-end flow" section (arrow + two URL bullets + signature bullets). The Figure at the top already conveys the visual; signature behavior is documented on webhook-verification.mdx. - Drop the "Working with triggers" 6-step list. The Next steps cards orient readers to the workflow pages, which own the step-by-step content. - Add a single-sentence note between the trigger types table and the Accordions: "If you bring your own OAuth app for a webhook trigger, you may need to register the Composio-issued ingress URL with the provider once per OAuth app — see Configuring the webhook endpoint." Composio handles it for you in most cases. subscribing-to-events.mdx - Remove the top "two webhook URLs" callout. The page is about subscriptions; bringing in webhook endpoints here added complexity that belongs on the concept and workflow pages, not here. Net: triggers.mdx goes from ~85 lines to ~42; concepts stay separated per page (subscription on its own page, endpoint on creating-triggers). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 19:07 UTC 5aa9430d748b8462f9af7eb78fb45b159702cc07
2 files changed +3 -49
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
-7
@@ -4,13 +4,6 @@ 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).** 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 -
7 ## Webhooks
8
9 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
+3 -42
@@ -8,53 +8,14 @@ When events occur in apps — a new Slack message, a GitHub commit, an incoming
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 subscription URL via HTTP POST" caption="How triggers deliver events from apps to your application" />
10
11 -## Two delivery types
11 +## Two trigger types
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, processes the payload, and fans the event out to matching trigger instances. | Slack, Asana, Notion, Outlook, ... |
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 -```
23 -provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your application
24 -```
25 -
26 -Two URLs sit on opposite sides of Composio, both configured once:
27 -
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 -
33 -- **At ingress**, every inbound request is verified against the signing secret on the webhook endpoint. Unsigned or tampered requests are rejected before any trigger fires. When Composio configures the endpoint, the signing secret comes from the connected account's credentials; when you configure it, you store the secret on the endpoint yourself.
34 -- **At delivery**, every webhook Composio sends to your endpoint is signed with your subscription secret — verify it as described in [Verifying webhooks](/docs/webhook-verification).
35 -
36 -## Working with triggers
37 -
38 -<Steps>
39 -<Step>
40 -**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.
41 -</Step>
42 -<Step>
43 -**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.
44 -</Step>
45 -<Step>
46 -**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.
47 -</Step>
48 -<Step>
49 -**Create the trigger** scoped to a user's connected account — see [Creating triggers](/docs/setting-up-triggers/creating-triggers).
50 -</Step>
51 -<Step>
52 -**Receive events** at your subscription URL, [verify the signature](/docs/webhook-verification), and route on `metadata.trigger_slug`.
53 -</Step>
54 -<Step>
55 -**Manage** triggers as needed — see [Managing triggers](/docs/setting-up-triggers/managing-triggers).
56 -</Step>
57 -</Steps>
18 +If you bring your own OAuth app for a webhook trigger, you may need to register the Composio-issued ingress URL with the provider once per OAuth app so events can flow into Composio — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) on the Creating triggers page. Composio handles this for you in most cases.
19
20 <Accordions>
21 <Accordion title="What is a trigger type?">