Skip to content

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

Anshu Garg916894fbc0ad
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
index 3cf8a112e..24cecad5d 100644
--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx
+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
@@ -1,7 +1,7 @@
---
title: Creating triggers
-description: Inspect a trigger type, create the instance, and configure the webhook endpoint when required
-keywords: [triggers, create trigger, trigger config, webhook endpoint, signing secret]
+description: Inspect a trigger type and create the instance via the SDK or the dashboard
+keywords: [triggers, create trigger, trigger config]
---
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
<Callout type="info" title="Prerequisites">
- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
- A connected account for the user whose events you want to capture
+- 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). 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.
+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.
## Using the SDK
@@ -87,7 +88,7 @@ Trigger instances default to the `'latest'` toolkit version. If your code parses
## Configuring the webhook endpoint
-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.
+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.
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:
@@ -245,7 +246,7 @@ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
## What to read next
<Cards>
- <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
+ <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" />
<Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures so you know payloads came from Composio" />
<Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
</Cards>
diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdx
index bd402b939..f10c3ea17 100644
--- a/docs/content/docs/triggers.mdx
+++ b/docs/content/docs/triggers.mdx
@@ -12,38 +12,21 @@ When events occur in apps — a new Slack message, a GitHub commit, an incoming
| Type | What happens | Examples |
|---|---|---|
-| **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, ... |
-| **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 |
-
-The delivery type is a property of the trigger type, not something you choose.
-
-## Setup at a glance
-
-Two pieces of setup, both one-time:
-
-| Piece | When it's needed | Scope | Where it's documented |
-|---|---|---|---|
-| **Webhook subscription** — your URL where Composio delivers signed events | Always | Once per project | [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
-| **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) |
-
-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.
-
-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.
+| **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, ... |
+| **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 |
## End-to-end flow
For every webhook trigger, an event takes the same path on the way to your application:
```
-provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your endpoint
+provider event ──▶ Composio ingress ──▶ trigger fan-out ──▶ webhook subscription ──▶ your application
```
-Two webhook URLs sit on opposite sides of Composio. Don't confuse them:
+Two URLs sit on opposite sides of Composio, both configured once:
-| URL | Direction | Who configures it |
-|---|---|---|
-| **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) |
-| **Webhook subscription** (your URL) | Composio → your application | You, once per project — see [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) |
+- **Webhook subscription** — your URL where Composio delivers signed events. One per project. See [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events).
+- **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.
Composio verifies signatures on both hops:
@@ -89,8 +72,9 @@ Triggers are scoped to a connected account. If you haven't set up authentication
## Next steps
<Cards>
- <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" />
- <Card icon={<Plug />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
+ <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" />
+ <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" />
+ <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" />
<Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Verify webhook signatures and understand payload versions" />
<Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
<Card icon={<BookOpen />} title="Example: Gmail labeler" href="/cookbooks/gmail-labeler" description="Build an automated email labeling agent using triggers" />