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, 21:00 UTC
docs(triggers): unify webhook-endpoint concept end-to-end [PLEN-2435] (#3361)
## What this PR is The trigger docs predate the current webhook-endpoints model and never explained it. The site has zero mentions of webhook endpoints, signing secrets at ingress, or the trigger-type flag that tells you whether endpoint setup is required. This PR fixes that gap end-to-end and surfaces the per-toolkit setup on the toolkit pages where customers look. ## The mental model the docs now teach **Two delivery types:** webhook (provider pushes events to Composio in real time) or polling (Composio polls). Determined by the trigger type. **Two pieces of setup, both one-time:** | Piece | When it's needed | Scope | |---|---|---| | **Webhook subscription** — your URL where Composio delivers signed events | Always | Once per project | | **Webhook endpoint** — the URL the provider posts events to | Only when the trigger type's `requires_webhook_endpoint` flag is true | Once per OAuth app | **Discovery is at the trigger level.** When you inspect a trigger type with `composio.triggers.get_type()`, the response includes a `requires_webhook_endpoint` flag. If true, configure the endpoint before creating the trigger; if false, just create. With Composio-managed OAuth apps the flag is always false. The trigger creation call also returns a `400` if the flag is true and no endpoint exists yet. The toolkit-level schema endpoint (`GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=...`) is documented as a sub-step inside the configuration walkthrough — it's the source of truth for *which credentials* the endpoint needs once you know you're configuring one. It's not the upfront check. ## What I changed (10 files) ### Conceptual docs (`/docs/...`) | File | Change | |---|---| | `docs/triggers.mdx` | New overview structure: two delivery types → setup-at-a-glance table → end-to-end flow with the two-URLs table → Working-with-triggers steps that lead with "inspect the trigger type." No upfront schema-endpoint check; no toolkit-name lists. | | `docs/setting-up-triggers/creating-triggers.mdx` | Reordered. SDK and dashboard sections now come first (the common path); the 5-step "Configuring the webhook endpoint" walkthrough is last, gated behind "skip unless your trigger needs it." SDK code samples print `requires_webhook_endpoint` / `requiresWebhookEndpoint` alongside `config` so the discovery moment is visible in-line. | | `docs/setting-up-triggers/subscribing-to-events.mdx` | Top callout reframed around the flag instead of toolkit names. | | `docs/webhook-verification.mdx` | Two-signatures callout. **Ingress signature verification** section reframed around the flag. | | `docs/troubleshooting/triggers.mdx` | **Webhook endpoint issues** section: header drops the toolkit names; lead-in references the flag. Failure modes unchanged. | | `docs/glossary.mdx` | Trigger entry simplified to two delivery types. New Webhook Endpoint and Webhook Subscription entries, both phrased around the flag. | | `docs/setting-up-triggers/meta.json` | No new pages — the walkthrough lives in `creating-triggers.mdx`. | ### Toolkit-page FAQs (`/toolkits/...`) Toolkit pages (e.g. `/toolkits/slack`) get triggers and tools server-side from Apollo (`/api/v3/triggers_types`, `/api/v3/tools`). The only piece of per-toolkit content in this repo is `content/toolkits/faq/{slug}.md` — plain markdown rendered as a FAQ accordion at the bottom of the toolkit page. | File | Change | |---|---| | `content/toolkits/faq/slack.md` | Rewrite the **"How do I set up Slack event webhooks?"** answer: it pointed at the legacy `/trigger_instances/slack/default/handle` URL. Replace with the webhook_endpoints flow (POST endpoint → PATCH signing secret → optional `app_token` → paste URL into Event Subscriptions). Lead with "Composio-managed credentials = nothing to do." Update **"Why aren't my Slack triggers working?"** to reference the same flow. | | `content/toolkits/faq/notion.md` | Add **"How do I set up Notion webhook triggers?"** with the same Composio-managed-vs-your-own split. Step 1 calls the schema endpoint to discover required fields, since I don't want to invent Notion-specific field names. | Both FAQ entries link to `/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint` for the canonical reference. ## What's deliberately NOT in this PR - **No V1/V2 split in the prose.** Per direction: keep the docs unified around the current model. V1 isn't mentioned in user-facing copy. The V2 announcement changelog still exists at `/docs/changelog/2026/04/27` for historical reference. - **No invented vocabulary.** Earlier drafts had "user-level webhook" and "app-level webhook endpoint" as named delivery models — both removed. - **No standalone V2 setup page.** The walkthrough is folded into `creating-triggers.mdx` so readers don't context-switch mid-flow. - **No API reference changes.** All API ref pages under `/reference/api-reference/webhooks/` are auto-generated by the `docs-update-data` workflow from Apollo's OpenAPI export — see Companion PR. ## Companion PR — must merge with this one **[#3238 — docs/auto-update-data](https://github.com/ComposioHQ/composio/pull/3238)** is the auto-update PR (open since 2026-04-18). It contains the regenerated `webhooks/index.mdx` and the latest `openapi.json`, both of which include the new `webhook_endpoints` CRUD operations. **That PR is what surfaces the API reference pages** (`postWebhookEndpoints`, `getWebhookEndpoints`, `getWebhookEndpointsByNanoId`, `postWebhookEndpointsByNanoId`, `patchWebhookEndpointsByNanoId`). Verified the auto-PR is correct: - Branch `docs/auto-update-data`, force-pushed every cycle (every 5 hours) by `peter-evans/create-pull-request`. - Latest commit `2026-05-07T10:42:33Z`. Single commit. **14 files**, all in the expected auto-generated set: `docs/content/reference/api-reference/*`, `docs/content/reference/v3/api-reference/*`, `docs/content/reference/meta-tools/*`, `docs/public/data/*`, `docs/public/openapi*.json`. Zero unrelated changes. - `+27,173 / -16,704` lines come from `openapi.json` (~31k lines) and `toolkits.json` (~6.7k lines) being fully regenerated. Review by file list, not by line count. - Status: `mergeStateStatus: BLOCKED, reviewDecision: REVIEW_REQUIRED`. All CI green (CodeQL, Vercel preview). Either PR can merge first; they touch disjoint files. Both must be in for the trigger story to be complete. ## Two open product items (separate from this PR) 1. **`requires_webhook_endpoint` flag on trigger types.** This PR's code samples and conceptual prose write against this flag as the discovery mechanism. Per discussion, the product team will expose it on the trigger type / SDK. If the field name shipped is different, this PR will need a small follow-up rename (one place in `triggers.mdx`, two places in `creating-triggers.mdx`'s code samples, plus the cross-references in `subscribing-to-events.mdx`, `webhook-verification.mdx`, `troubleshooting/triggers.mdx`, and `glossary.mdx`). 2. **`GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=...` not in the OpenAPI spec.** This endpoint is documented (used inside the configuration walkthrough) but Apollo isn't exporting it. Without Apollo source in this repo I can't say whether it's missing the `Webhooks` tag, marked `x-internal: true`, or just unannotated. The endpoint works in production today; it just doesn't show up in the auto-generated API reference. Action item on the Apollo side. ## Test plan - [x] `bun x fumadocs-mdx && bun run scripts/validate-links.ts` — 0 errors after each commit - [ ] Reviewer: open the Vercel preview and confirm: - `/docs/triggers` reads coherently end-to-end (no V1/V2 in prose; setup-at-a-glance table is accurate) - `/docs/setting-up-triggers/creating-triggers` — SDK/dashboard sections come first; walkthrough at the bottom is clearly skippable - `/toolkits/slack` and `/toolkits/notion` FAQ accordions show the new webhook setup steps - The `requires_webhook_endpoint` flag references read correctly across all the trigger pages 🤖 Generated with [Claude Code](https://claude.com/claude-code)
No changes.