docs(triggers): unify webhook-endpoint concept end-to-end [PLEN-2435]#3361
Conversation
Trigger docs predate Webhook Triggers V2 — they describe a single "webhook trigger" model in which Composio handles ingress automatically. That story is no longer complete: V2 toolkits (Slack today, more to follow) require a one-time, project-level setup where the user registers an OAuth app's signing secret on a webhook_endpoint and points the provider's app dashboard at a Composio-issued URL. This change rewrites the trigger surface around three delivery models: - Polling — Composio polls the provider on a schedule (e.g. Gmail). - User-level webhook — Composio auto-registers a per-user webhook with the provider on trigger creation (Asana, GitHub, Outlook, ...). - App-level webhook endpoint (V2) — the user creates a webhook_endpoint per OAuth app, stores the provider's signing secret, and points the provider at the issued ingress URL (Slack). Files: - triggers.mdx — overview rewritten around the three delivery models, end-to-end flow with both webhook URLs (ingress vs subscription), and ingress-side signature verification. - setting-up-triggers/configuring-webhook-endpoints.mdx — new page, full V2 walkthrough (Slack) using Steps: discover schema → create endpoint → store signing secret → optionally add app token → point provider at URL → confirm verified_at. Also covers PATCH vs POST update semantics and V1 → V2 migration triggers. - setting-up-triggers/creating-triggers.mdx — note V2 prerequisite in the prerequisites callout; link to new page in next steps. - setting-up-triggers/subscribing-to-events.mdx — top-of-page callout disambiguating the two webhook URLs (ingress vs subscription). - setting-up-triggers/meta.json — register new page, ordered after creating-triggers. - webhook-verification.mdx — split responsibility callout at the top (Composio verifies ingress, you verify delivery); add an "Ingress signature verification (V2)" section. - troubleshooting/triggers.mdx — V2-specific failure modes (signing-secret missing, verified_at null, missing app_token, replay-window rejections). - glossary.mdx — "Trigger" entry rewritten around three models; new "Webhook Endpoint" and "Webhook Subscription" entries. Note: the corresponding webhook_endpoints API reference pages are auto-generated from Apollo's OpenAPI export by the docs-update-data workflow. They are already present on PR #3238 (the open auto-update-data PR) and will surface in the API reference the moment that PR merges. Separately: GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=... is referenced in the changelog and on the new doc page but is not in Apollo's exported OpenAPI spec. That's an Apollo annotation gap to fix on the backend side; it does not block this docs PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Claude finished @anshugarg15's task in 2m 31s —— View job Docs reviewApplied the docs-reviewer checklist to all 8 changed files.
FindingsOne factual issue.
In the new "End-to-end flow" table, the V1 ingress path is documented as
A V1 user reading this table to understand the two URL shapes would copy the wrong version prefix. Fix: -| **Ingress** (`/api/v3.1/trigger_instances/.../handle` for V1, `/api/v3.1/webhook_ingress/...` for V2) | Provider → Composio | Composio (V1, automatic) or you, once per OAuth app (V2 — see [Configuring webhook endpoints](/docs/setting-up-triggers/configuring-webhook-endpoints)) |
+| **Ingress** (`/api/v3/trigger_instances/.../handle` for V1, `/api/v3.1/webhook_ingress/...` for V2) | Provider → Composio | Composio (V1, automatic) or you, once per OAuth app (V2 — see [Configuring webhook endpoints](/docs/setting-up-triggers/configuring-webhook-endpoints)) |What I checked and is fine
Once the V1 path typo is fixed, this looks good. |
… framing Per review: the conceptual docs should describe the current product — one webhook-endpoint concept whose only axis is who configures it. V1/V2 split was an implementation detail that didn't belong in user- facing prose. Per-OAuth-app endpoint setup also doesn't apply when you use Composio-managed credentials, which the previous draft failed to call out. Concrete changes vs the previous commit: - Drop "V1", "V2", "user-level webhook", "app-level webhook endpoint", and "delivery models" from all conceptual docs (triggers.mdx, creating-triggers.mdx, subscribing-to-events.mdx, webhook-verification.mdx, troubleshooting/triggers.mdx, glossary.mdx). - Remove the standalone configuring-webhook-endpoints.mdx page; fold the walkthrough into creating-triggers.mdx as a "Configuring the webhook endpoint" section. Revert meta.json accordingly. - triggers.mdx now frames a single webhook-endpoint concept with two configurations: Composio-managed (default for everything; required with Composio-managed OAuth apps) vs you-managed (your own OAuth app on toolkits like Slack and Notion today). - Make the Composio-managed-OAuth case explicit: if you use Composio-managed credentials, no manual webhook-endpoint setup applies. Surfaced as a callout in triggers.mdx and creating-triggers.mdx. - The schema endpoint (GET /api/v3.1/webhook_endpoints/schema?toolkit_slug=...) is documented as the source of truth for whether your toolkit needs manual configuration: empty setup_fields = Composio handles it (Asana, etc.); non-empty = you handle it (Slack, Notion). - creating-triggers.mdx: walkthrough now uses 5 numbered steps (discover → create → store credentials → point provider at URL → confirm verified_at), plus an "Updating an endpoint" subsection covering PATCH vs POST semantics and how to list endpoints. - troubleshooting/triggers.mdx: section header drops "V2", lead with a one-line note that issues only apply to user-managed endpoints. - glossary.mdx: Trigger entry simplified to two delivery types; Webhook Endpoint entry rewritten without V2 vocabulary. - webhook-verification.mdx: ingress section drops "V2" framing and explains the two cases for where the signing secret comes from (Composio-managed credentials vs PATCHed by the user). Note: the schema endpoint is referenced in the docs but is not in Apollo's exported OpenAPI spec, so no auto-generated reference page exists for it. CRUD on /webhook_endpoints is in the spec and will surface via auto-update PR #3238. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 46s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the updated diff.
Looks goodThe V1/V2 inconsistency I flagged on the previous push is fully resolved — commit Other things I checked and that are fine:
Approving from my side. Ready when you are. |
anshugarg15
changed the title
Toolkit pages (e.g. /toolkits/slack) get triggers/tools server-side
from Apollo and pull a per-toolkit FAQ from
content/toolkits/faq/{slug}.md. The Slack FAQ already had a
"How do I set up Slack event webhooks?" entry but it pointed at the
legacy ingress URL; Notion had no webhook entry at all.
- slack.md: rewrite the webhook setup answer to use the
webhook_endpoints flow (POST /webhook_endpoints, PATCH signing
secret, optional app_token, paste URL into Event Subscriptions).
Lead with "Composio-managed credentials = nothing to do."
Update the "Why aren't my Slack triggers working?" answer to
reference the same flow.
- notion.md: add a "How do I set up Notion webhook triggers?" entry
with the same Composio-managed-vs-your-own split. Step 1 calls
the schema endpoint as the source of truth for which credentials
Notion needs, since I don't want to invent field names.
- Both link to /docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint
for the canonical reference.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 3m 34s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
One issueThree new absolute internal links in the FAQ files violate
Per The targets all exist as relative paths today (verified Fix: # docs/content/toolkits/faq/slack.md:60
-For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# docs/content/toolkits/faq/slack.md:79
-For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
+For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](/docs/troubleshooting/triggers) for the full list of failure modes.
# docs/content/toolkits/faq/notion.md:53
-For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).Everything else looks good
Once the three absolute URLs are flipped to relative, this is good to merge. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 0cb8a52. Configure here.
|
|
||
| <GlossaryTerm name="Webhook Subscription"> | ||
| The URL Composio delivers signed events to in your application. One per project, configured via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks). See [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events). | ||
| </GlossaryTerm> |
There was a problem hiding this comment.
Glossary entries break alphabetical ordering
Low Severity
The new Webhook Endpoint and Webhook Subscription entries are inserted between Trigger Instance and User ID, breaking the glossary's alphabetical order. Since "U" sorts before "W", the User ID entry needs to appear before both new Webhook entries.
Reviewed by Cursor Bugbot for commit 0cb8a52. Configure here.
Targeted English fixes on triggers.mdx:
- Webhook endpoints table — drop the duplicated "for on your behalf"
("register webhooks for on your behalf" → "register webhooks on
your behalf"), reflow both rows to read as full sentences instead
of fragmented clauses.
- "There are two ways an endpoint gets configured" → "An endpoint
is configured in one of two ways" (less awkward).
- "more toolkits move onto this flow" → "more toolkits adopt this
flow over time" (idiomatic).
- Two webhook URLs table — "you for your-own-OAuth on toolkits"
→ "you when you bring your own OAuth app on a toolkit".
- Ingress signature paragraph — "the signing secret is sourced
from" → "the signing secret comes from"; tighten clauses.
- Working with triggers / "Configure ingress" step — split the
long compound sentence into two; replace parenthetical
"(only when needed)" with a clearer lead-in.
- Next steps card — "(when needed)" → "if your toolkit needs it".
No structural changes; the table and section structure are
unchanged, just the copy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 37s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The prose polish itself looks good
But two issues from prior reviews are still unaddressedThe latest push didn't touch the FAQ files or the glossary, so both findings still apply on this commit. 1. Three absolute internal URLs in the FAQ files (from my 11:53Z review) Confirmed still present via
Per 2. Glossary alphabetical ordering (from Cursor Bugbot)
Move Other things I checked and that are fine
Once the three absolute URLs are flipped to relative and the |
…point 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>
|
Claude finished @anshugarg15's task in 4m 10s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
Blocker —
|
| File:Line | Current |
|---|---|
docs/content/toolkits/faq/slack.md:60 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint |
docs/content/toolkits/faq/slack.md:79 |
https://docs.composio.dev/docs/troubleshooting/triggers |
docs/content/toolkits/faq/notion.md:53 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint |
docs/CLAUDE.md rule #10: "Internal links use relative paths, never absolute. The link checker only validates relative links; absolute URLs silently bypass it and rot over time." Replace each https://docs.composio.dev/docs/... with /docs/....
2. Glossary alphabetical ordering (from Cursor Bugbot) — glossary.mdx:126-132 puts Webhook Endpoint and Webhook Subscription before User ID (:134-136), but U sorts before W. The <Glossary> component renders entries in source order. Move the User ID block above the Webhook Endpoint block.
Other things I checked and that are fine
- Anchors all resolve (re-checked):
#configuring-the-webhook-endpoint(creating-triggers.mdx:94),#using-the-sdk(creating-triggers.mdx:13),#ingress-signature-verification(webhook-verification.mdx:200),#how-do-i-set-up-slack-event-webhooks(slugifies cleanly from FAQ heading). - Icon imports (
Plug,RouteIcon,ShieldCheck,Wrench,BookOpen,Key,Zap) are all indocs/mdx-components.tsx:29-46. - Restructure is consistent. SDK and dashboard sections lead; the 5-step walkthrough is correctly gated under "Skip this section unless you already know you need it." End-to-end ingress vs subscription URL framing in
triggers.mdx,subscribing-to-events.mdx, andwebhook-verification.mdxis consistent. - Walkthrough completeness. The 5 walkthrough steps (schema → create → store credentials → point provider at URL → confirm
verified_at), the "store credentials before flipping the URL" warning, the Slack auto-disable window, and the PATCH-vs-POST update semantics are all preserved and concrete. - Glossary entries (separate from the alphabetical-order issue) keep the two URL shapes distinct and link to the right pages.
Once the build is green (either ship the SDK field first, or revert the pivot to the schema-endpoint discovery model) and the two prior-review items above are addressed, this is good to merge.
• Branch: docs/triggers-webhook-endpoints
•
…ples The TypeScript code block in creating-triggers.mdx accessed triggerType.requiresWebhookEndpoint, which doesn't exist on the SDK's TriggerType today (see ts/packages/core/src/types/triggers.types.ts:152). Twoslash type-checks all TS code blocks at build time per docs/CLAUDE.md rule 1, so the build failed on Vercel. Drop the property reads (Python and TypeScript) so the samples are valid against today's SDK. Conceptual prose still references the requires_webhook_endpoint flag — the discovery story is unchanged, just the code samples no longer claim the field exists yet. When the SDK ships the field, add the reads back. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 24s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The Twoslash blocker is resolved
This is the right shape of fix for now. When the SDK lands the field, adding the reads back is a localized change to the two code blocks at Two issues from prior reviews are still unaddressedThe latest commit only touched 1. Three absolute internal URLs in FAQ files (from my 11:53Z review) Confirmed still present via
Fix: # docs/content/toolkits/faq/slack.md:60
-For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# docs/content/toolkits/faq/slack.md:79
-For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
+For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](/docs/troubleshooting/triggers) for the full list of failure modes.
# docs/content/toolkits/faq/notion.md:53
-For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).2. Glossary alphabetical ordering (from Cursor Bugbot)
Other things I checked and that are fine
Once the three absolute URLs are flipped to relative and the |
…n" in flow diagram
The rightmost box in the triggers-flow figure (the receiver inside
"Your Application") was labelled "Webhook Endpoint", which conflicts
with our docs vocabulary: webhook_endpoint is the Composio-side
resource that owns the ingress URL we register with the provider, not
the URL the customer's app exposes. The customer-side URL is a
webhook_subscription.
Update both the light and dark SVGs to label that box "Webhook
Subscription". Also reword the alt text on the Figure in triggers.mdx
("your webhook endpoint" → "your webhook subscription URL") so the
non-visual experience matches.
The leftmost box "Webhook Receiver" is unchanged — it's a generic
descriptive label for Composio's intake side, not a vocabulary term.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 21s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The figure rename is correct
Alt text on the Two issues from prior reviews are still unaddressedThe latest commit only touches three files ( 1. Three absolute internal URLs in FAQ files (from my 11:53Z review) Confirmed still present via
Per Fix — strip # docs/content/toolkits/faq/slack.md:60
-For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# docs/content/toolkits/faq/slack.md:79
-For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
+For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](/docs/troubleshooting/triggers) for the full list of failure modes.
# docs/content/toolkits/faq/notion.md:53
-For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).2. Glossary alphabetical ordering (from Cursor Bugbot)
Other things I checked and that are fine
Once the three absolute URLs are flipped to relative and the |
…ng-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>
|
Claude finished @anshugarg15's task in 2m 30s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The trim is the right call
Anchors I sanity-checked after the trim: Restoring the "Configuring the webhook endpoint" section inside Two issues from prior reviews are still unaddressedThe latest commit only touches 1. Three absolute internal URLs in FAQ files (from my 11:53Z review) Confirmed still present via
Fix — strip # docs/content/toolkits/faq/slack.md:60
-For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# docs/content/toolkits/faq/slack.md:79
-For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
+For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](/docs/troubleshooting/triggers) for the full list of failure modes.
# docs/content/toolkits/faq/notion.md:53
-For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).2. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the three absolute URLs are flipped to relative and the |
…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>
|
Claude finished @anshugarg15's task in 2m 33s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The slim is the right call, and the per-page concept separation is now clean
After this commit each page owns one concept:
That's a cleaner mental model than the pre-trim version. Anchors I sanity-checked after the trim:
All resolve. No stale references to removed anchors ( Icons ( Two issues from prior reviews are still unaddressedThe latest commit only touched 1. Three absolute internal URLs in FAQ files (from my 11:53Z review) Confirmed still present via
Fix — strip # docs/content/toolkits/faq/slack.md:60
-...see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+...see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# docs/content/toolkits/faq/slack.md:79
-...See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
+...See [Triggers troubleshooting](/docs/troubleshooting/triggers) for the full list of failure modes.
# docs/content/toolkits/faq/notion.md:53
-...see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+...see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).2. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the three absolute URLs are flipped to relative and the |
The intro was cramming five things into one runaway sentence: where you can create triggers, the Composio-managed flow, the bring-your-own-OAuth flow, the requires_webhook_endpoint_setup flag, and the 400 status code. Plus a meta "see Configuring below" pointer. Reduced to two short sentences. Flag name and 400 status drop out — the Configuring section's own intro already explains both, so they don't need to be teased here. Reader gets oriented (SDK or dashboard) with a soft anchor for the conditional case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 3m 11s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The intro tightening is the right call
Drops the flag name and the Four issues from prior reviews are still unaddressed
1. Secret-callout claim still contradicts the OpenAPI on this branch (highest impact — silently breaks customers who follow the docs)
Re-verified on
A customer who lost their secret follows the new copy, -Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. FAQ ↔ deleted-troubleshooting-section mismatch (from my 15:27Z review) Commit
A Slack customer hitting one of those four modes, clicking the link, and landing on the page now sees only generic "check permissions / publicly accessible URL / trigger enabled / logs" content — none of the four specific failures. Pick:
3. Two absolute internal URLs in Confirmed via
# slack.md:27
-...see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+...see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# slack.md:39 (also see issue 2 above)
-See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for...
+See [Triggers troubleshooting](/docs/troubleshooting/triggers) for...4. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the secret-callout claim is reconciled with the OpenAPI (most important — silent HMAC verification failure for customers who follow the docs), the FAQ↔troubleshooting mismatch is resolved, the two absolute URLs are flipped to relative, and the
|
…bullets The two prose paragraphs about per-tenant guarantees and ingress signature checks were dense walls of text. Restructure as bullets matching the V2 announcement changelog's format. Each item now stands on its own line, scannable. Word-level edits: - "since providers accept" → "providers accept" (drop redundant conjunction; colon does the work) - "The upside:" → "In return," — acknowledges it's a trade - "every project becomes its own webhook tenant with isolated..." → restructured as a lead-in followed by 4 bullets - "Provider events are verified at ingress against the endpoint's signing secret before any trigger fires —" → "Every inbound event is signature-checked at ingress before any trigger fires:" — active, shorter - Replay protection bullet is no longer a "for providers..." parenthetical; it's its own item Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 3m 3s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest two pushes (
The latest two commits look goodBoth edits are scoped to
Anchors I rechecked after the edits — all resolve:
Icons and Twoslash unaffected (commits don't touch any code blocks or component imports). Four issues from prior reviews are still unaddressedThe latest two commits only touched 1. Secret-callout claim contradicts the OpenAPI on this branch — highest impact Still present at
OpenAPI on
A developer who lost their secret follows the new copy, -Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. FAQ ↔ deleted-troubleshooting-section mismatch (introduced in
But verified via
3. Two absolute internal URLs in
Per 4. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the four items above are resolved (the secret-callout claim being the most impactful — it'll silently break customers who follow the docs), this is good to merge.
|
…d as inspection note
Step 5 ("Confirm the endpoint is verified" by GETting and checking
verified_at) wasn't in the V2 changelog walkthrough. The changelog
goes from "point provider dashboard at URL" straight to "create V2
trigger instances" — the trigger create call is itself the natural
confirmation, since it'll fail if the endpoint didn't verify.
Verified in the changelog: `verified_at` IS a real field returned by
GET /api/v3.1/webhook_endpoints/{id} (changelog line 44 lists the
endpoint as "Get a single endpoint, including verified_at"). So the
field exists; just the standalone confirmation step doesn't.
- Step 4's last sentence now ends with the natural next-action
("Once the provider saves the URL, retry the trigger creation
call from Using the SDK") instead of a separate Step 5.
- Add a GET-by-id example to "Updating an endpoint" so verified_at
remains discoverable as an inspection tool when needed, just not
promoted to a mandatory step.
Walkthrough collapses to 4 steps, matching the changelog structure.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two issues flagged on review:
1. "Retry the trigger creation call" in step 4 implied the user had
already failed once. First-time setup users hadn't tried at all.
Reword to "head back to Using the SDK to create your trigger".
2. verified_at isn't universal — providers that don't run a URL
verification handshake never populate it. Telling readers to
check verified_at would mislead them on toolkits that don't
verify. Remove all verified_at references from the docs:
- creating-triggers.mdx Step 4 ending: drop the verified_at
framing; reword the verification challenge sentence to lead
with "for providers that issue a verification challenge on
save" so providers without a handshake aren't misframed.
- creating-triggers.mdx "Updating an endpoint": drop the
"(handy for checking verified_at after a provider re-save)"
parenthetical from the GET-by-id example.
- slack.md FAQ: simplify the "Why aren't my Slack triggers
working?" answer to just point at the troubleshooting page,
dropping the enumerated failure-mode list (which referenced
verified_at and is no longer on the troubleshooting page
anyway).
The changelog mention of verified_at (line 44 of the V2 announcement)
is left intact — historical reference, shouldn't be retroactively
edited.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 3m 34s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest two pushes (
The latest two commits are goodBoth edits remove content that would have misled readers, leaving the walkthrough cleaner:
The same commit also resolves my earlier flag about the FAQ ↔ deleted-troubleshooting-section mismatch. Anchors I resanity-checked: Three issues from prior reviews are still unaddressedThe latest two commits don't touch the secret callouts, the FAQ link path-form, or the glossary, so all three findings still apply. 1. Secret-callout claim still contradicts the OpenAPI on this branch — highest impact Still present at
OpenAPI on
A customer who lost their secret follows the new copy, -Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. Two absolute internal URLs in Confirmed via
Per 3. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the secret-callout claim is reconciled with the OpenAPI (most important — silent HMAC verification failure for customers who follow the docs), the two absolute URLs are flipped to relative, and the
|
…before SDK, fix bullet wording, single PATCH
Multiple corrections from review:
1. Frontmatter description reverted to original
"Create trigger instances via the dashboard or SDK" (was edited
to a longer string that wasn't part of this PR's scope).
2. SDK section's first paragraph reverted to original
("Before creating a trigger, inspect the trigger type to see
what configuration it requires. Then create the trigger with
the required config."). The previous edit added a "...whether
you need to set up a webhook endpoint first" tail that drifted
from the section's original framing.
3. Code-comment reverts in both Python and TypeScript samples:
- "# Inspect the trigger type" -> "# Check what configuration is required"
- "# {properties...}" -> "# Returns: {properties...}"
- same in TS with // comments
These were collateral edits during prior passes; the originals
were fine.
4. Dashboard step 4 reverted to original
("Choose a trigger type and fill in the required configuration").
The added sentence claimed the dashboard prompts for webhook
endpoint configuration, which it doesn't.
5. Section order: Configuring the webhook endpoint now comes
before Using the SDK. Anyone who needs to configure encounters
it before scrolling past SDK examples. Users who don't need
it skip naturally — the section's intro spells out the
conditions. Last sentence of step 4 changed from "head back
to" -> "continue to" since SDK is now below.
6. Per-project capabilities bullet reworded — "Its own signing
secret and app-level token" -> "Project-scoped credentials —
the signing secret and app-level token you provide are stored
against this project alone." Composio doesn't provide the
secrets; the customer does. The capability is project-scoping,
not credential issuance.
7. Step 3 consolidated into a single PATCH that sends both fields
at once (previously two separate PATCH requests, one per
field). One request is the right API pattern; the Slack-specific
guidance about where to find each credential is preserved as
a bullet list under the curl block.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 45s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The latest commit's changesThree substantive edits in
No new factual issues from this commit. Three issues from prior reviews are still unaddressedThe latest commit only touches 1. Secret-callout claim still contradicts the OpenAPI on this branch — highest impact Re-verified
Re-verified
A customer who lost their secret follows the new copy, -Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. Two absolute internal URLs in Confirmed via
Per # slack.md:27
-...see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+...see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# slack.md:39
-See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers).
+See [Triggers troubleshooting](/docs/troubleshooting/triggers).3. Glossary alphabetical ordering (Cursor Bugbot)
Other things I checked and that are fine
Once the secret-callout claim is reconciled with the OpenAPI (most important — silent HMAC verification failure for customers who follow the docs), the two absolute URLs are flipped to relative, and the
|
anshugarg15
changed the title
| </Callout> | ||
|
|
||
| You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). | ||
| You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). Some webhook triggers also need a webhook endpoint configured first — covered in [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below. |
There was a problem hiding this comment.
Can we add a note that this is needed only for webhook triggers and not polling triggers?
This will help customers know when to stop reading if they are interested only in polling triggers.
| - **Its own ingress rate limit and backpressure budget** | ||
| - **Project-scoped credentials** — the signing secret and app-level token you provide are stored against this project alone, never shared across projects. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged challenge. | ||
| - **Clean fan-out** — events reach only that project's trigger instances | ||
| - **Per-project metering** |
There was a problem hiding this comment.
nit: please mention in brackets (in future) as we don't have metering right now
- Single Webhook Endpoints API pointer at Step 2 of creating-triggers, mirroring the Subscriptions API pointer pattern; same pointer added to the Webhook Endpoint glossary entry. - Reword Slack-walkthrough intro to direct readers to per-toolkit FAQ (Slack, Notion). - Add "How do I set up the Notion webhook ingress endpoint?" FAQ covering the reverse-direction verification flow (token from Composio pasted back into Notion). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 2m 18s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest push (commit
The 73a5ccf changes themselves look goodThree small additions, all factually consistent with the rest of the walkthrough:
Anchors I checked after the edits — all resolve: One new issue from
|
| Line | Content |
|---|---|
:10529 |
"The signing secret is returned only on creation." |
:10759, :10903, :11057 |
"description": "Masked signing secret (full secret only on create/rotate)" |
A customer who lost their secret follows the new copy, GETs the subscription, gets a masked value, pastes it into COMPOSIO_WEBHOOK_SECRET, and watches HMAC verification fail silently on every request. Pick (1) wait for companion PR #3238 to land an OpenAPI where the GET response's secret description no longer says "Masked", or (2) revert the wording:
-Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. Two (now three) absolute internal URLs in FAQ files (rule #10)
| File:Line | Current |
|---|---|
docs/content/toolkits/faq/slack.md:27 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint |
docs/content/toolkits/faq/slack.md:39 |
https://docs.composio.dev/docs/troubleshooting/triggers |
docs/content/toolkits/faq/notion.md:43 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#using-the-sdk (new in 73a5ccf) |
Per docs/CLAUDE.md rule #10: "Internal links use relative paths, never absolute. The link checker only validates relative links; absolute URLs silently bypass it and rot over time." Strip https://docs.composio.dev from each.
3. Glossary alphabetical ordering (Cursor Bugbot)
docs/content/docs/glossary.mdx re-checked: Webhook Endpoint at line 126, Webhook Subscription at line 130, User ID at line 134. Since U sorts before W and <Glossary> renders entries in source order (no sort, verified in docs/components/glossary.tsx), the visual list reads out of order. Move the User ID block (:134-136) above the Webhook Endpoint block (:126).
Other things I checked and that are fine
- Toolkit FAQ link targets resolve.
/toolkits/slackand/toolkits/notionboth resolve via the dynamic toolkit route (toolkit slugs inpublic/data/toolkits.json). /reference/api-reference/webhooksresolves as an existing page. The endpoint table on that page is auto-generated from OpenAPI by CI; once companion PR docs: update toolkits, API spec, and meta tools data #3238 lands, thewebhook_endpointsCRUD ops will appear there alongside the existingwebhook_subscriptionsops. Pointing at the page now is reasonable per the PR body's two-PR ordering note.- Notion FAQ flow is logically consistent with the walkthrough. Step 2 paste-URL-then-Step-3-read-token correctly reflects that Notion sends the verification token after the URL is registered (unlike Slack where the secret comes from the provider's dashboard before the URL is registered). The previously-flagged "PATCH-credentials-before-flipping-URL" warning at
creating-triggers.mdx:106-108is Slack-shaped and doesn't apply to Notion's reverse flow — this is correctly handled by Notion having its own FAQ. - Walkthrough completeness preserved at
creating-triggers.mdx:17-172: 4 setup steps (schema → create → store credentials → point provider at URL) + Updating-an-endpoint subsection. The "store credentials before flipping the URL" warning, the Slack ~36-hour auto-disable window, the per-triggerapp_tokenrequirement, the re-handshake-rejection security note, and the PATCH-vs-POST update semantics all preserved. - End-to-end flow disambiguation between ingress URL (provider → Composio) and subscription URL (Composio → your app) remains consistent across
triggers.mdx,subscribing-to-events.mdx, andwebhook-verification.mdx. requires_webhook_endpoint_setupis still prose-only (creating-triggers.mdx:19,glossary.mdx:127) — not on the SDK or OpenAPI yet, so Twoslash isn't affected. PR body tracks the SDK addition as a follow-up; canonical name (requires_webhook_endpointper the PR body vs.requires_webhook_endpoint_setupin the docs) still worth confirming with whoever owns the SDK addition before merging.
Once the secret-callout claim is reconciled with the OpenAPI (most important — silent HMAC verification failure for customers who follow the docs), the three absolute URLs are flipped to relative, and the User ID glossary entry is moved above the Webhook entries, this is good to merge.
- Branch:
docs/triggers-webhook-endpoints
The /reference/api-reference/webhooks page lists both Subscriptions and Endpoints operations on one page, so the generic page-level link was ambiguous about which API the prose was referring to. Each label now points to its create operation page (postWebhookSubscriptions / postWebhookEndpoints). Also moves the Webhook Endpoints API pointer up out of Step 2 into the section intro so it scopes the whole walkthrough. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 4m 25s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest two pushes (
New issue from
|
| File:Line | New link |
|---|---|
docs/content/docs/glossary.mdx:127 |
/reference/api-reference/webhooks/postWebhookEndpoints |
docs/content/docs/setting-up-triggers/creating-triggers.mdx:44 |
/reference/api-reference/webhooks/postWebhookEndpoints |
postWebhookEndpoints is the forthcoming webhook_endpoints CRUD op, which is only in the companion auto-update PR (#3238) — not in this branch's OpenAPI. Verified:
grep -c WebhookEndpoint docs/public/openapi.json docs/public/openapi-v3.json→0and0ls docs/content/reference/api-reference/webhooks/→ onlyindex.mdx- The
<ApiEndpointsTable>inwebhooks/index.mdxlists only thewebhook_subscriptionsops
Result: if this PR lands before #3238, both links will 404 in production. The PR body explicitly notes the two-PR coordination, so this is solvable by either (1) waiting for #3238 to merge first, or (2) reverting these two specific links back to /reference/api-reference/webhooks (the hub page that exists today and which the previous version of this PR used).
Note: Docs - Check Links CI is green on 0006e10 — the link checker's populate against getReferenceSource() does enumerate OpenAPI-generated pages, but the catch-all (home)/reference/[[...slug]] validator appears to accept postWebhookEndpoints as a slug match without strict page-existence. Either way, a reader clicking through on the deployed site after this PR ships standalone will 404.
# glossary.mdx:127
-...you configure it yourself once per OAuth app via the [Webhook Endpoints API](/reference/api-reference/webhooks/postWebhookEndpoints).
+...you configure it yourself once per OAuth app via the [Webhook Endpoints API](/reference/api-reference/webhooks).
# creating-triggers.mdx:44
-The walkthrough below uses Slack as the example and walks through the [Webhook Endpoints API](/reference/api-reference/webhooks/postWebhookEndpoints). ...
+The walkthrough below uses Slack as the example and walks through the [Webhook Endpoints API](/reference/api-reference/webhooks). ...Two unaddressed reviewer comments from @lingalarahul7's earlier review
The reviewer left an APPROVED review with two comments that haven't been addressed in subsequent pushes:
-
creating-triggers.mdx:15— "Can we add a note that this is needed only for webhook triggers and not polling triggers? This will help customers know when to stop reading if they are interested only in polling triggers." The current sentence ("Some webhook triggers also need a webhook endpoint configured first") implies it but doesn't say the page is webhook-only. A reader looking at polling triggers might still read through Configuring before realizing it's not for them. -
creating-triggers.mdx:32— "nit: please mention in brackets (in future) as we don't have metering right now" — the "Per-project metering" bullet currently reads as a present-tense capability.
Suggested:
# :15
-You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). Some webhook triggers also need a webhook endpoint configured first — covered in [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below.
+You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). Some webhook triggers also need a webhook endpoint configured first — covered in [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below. Polling triggers don't need this; you can skip straight to [Using the SDK](#using-the-sdk).
# :32
-- **Per-project metering**
+- **Per-project metering** (in future)Three issues from prior reviews are still unaddressed
1. Secret-callout claim still contradicts the OpenAPI on this branch — highest impact
Still present at webhook-verification.mdx:14 and :64:
Store the webhook secret securely as
COMPOSIO_WEBHOOK_SECRET. You can fetch it from the webhook subscription at any time or rotate it if it leaks.
Re-verified docs/public/openapi.json on HEAD:
| Line | Content |
|---|---|
:10529 |
"The signing secret is returned only on creation." (POST /webhook_subscriptions) |
:10759, :10903, :11057 |
"description": "Masked signing secret (full secret only on create/rotate)" (the secret field on GET, POST, and rotate-secret responses) |
A customer who lost their secret follows the new copy, GETs the subscription, gets a masked value, pastes it into COMPOSIO_WEBHOOK_SECRET, and watches HMAC verification fail silently. Pick (1) wait for companion PR #3238 to land an OpenAPI where the GET response's secret description no longer says "Masked", or (2) revert the wording:
-Store the webhook secret securely as `COMPOSIO_WEBHOOK_SECRET`. You can fetch it from the [webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) at any time or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) if it leaks.
+The full secret is only returned when you [create a webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) or [rotate it](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret); the [GET endpoint](/reference/api-reference/webhooks/getWebhookSubscriptionsById) returns a masked value. Store it securely as `COMPOSIO_WEBHOOK_SECRET`; if you lose it, rotate.2. Three absolute internal URLs in FAQ files (rule #10 violation)
Confirmed via grep 'docs.composio.dev':
| File:Line | Current |
|---|---|
docs/content/toolkits/faq/slack.md:27 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint |
docs/content/toolkits/faq/slack.md:39 |
https://docs.composio.dev/docs/troubleshooting/triggers |
docs/content/toolkits/faq/notion.md:43 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#using-the-sdk |
Per docs/CLAUDE.md rule #10: "Internal links use relative paths, never absolute. The link checker only validates relative links; absolute URLs silently bypass it and rot over time." Strip https://docs.composio.dev from each.
3. Glossary alphabetical ordering (Cursor Bugbot)
docs/content/docs/glossary.mdx re-checked: Webhook Endpoint at line 126, Webhook Subscription at line 130, User ID at line 134. Since U sorts before W and <Glossary> renders entries in source order (no sort, verified in docs/components/glossary.tsx), the visual list reads out of order. Move the User ID block (:134-136) above the Webhook Endpoint block (:126).
Other things I checked and that are fine
- The three "real" operation links added in
0006e10(postWebhookSubscriptions,getWebhookSubscriptionsById,postWebhookSubscriptionsByIdRotateSecret) all match the existing camelCase IDs incontent/reference/api-reference/webhooks/index.mdx's<ApiEndpointsTable>. - Changelog edit at
02-06-26-webhook-subscriptions-api.mdx:22— repointing from the hub page topostWebhookSubscriptionsis consistent with the rest of0006e10's pattern, and the operation exists today. - Anchors all resolve (re-checked):
#configuring-the-webhook-endpoint(creating-triggers.mdx:17),#using-the-sdk(creating-triggers.mdx:174),#using-the-dashboard(creating-triggers.mdx:236),#how-do-i-set-up-slack-event-webhooks(slugifies cleanly from FAQ heading),#how-do-i-set-up-the-notion-webhook-ingress-endpoint(slugifies cleanly). - Notion FAQ flow at
notion.md:17-43is logically consistent with Notion's reverse-verification flow (POST endpoint → paste URL → token arrives → paste back). The asymmetry vs. Slack's flow is called out up front. - Toolkit FAQ targets (
/toolkits/slack,/toolkits/notion) resolve via slugs frompublic/data/toolkits.json. - Twoslash unaffected. Code samples at
creating-triggers.mdx:181-227printtriggerType.configonly — no field that doesn't exist in the SDK yet. - Walkthrough completeness preserved at
creating-triggers.mdx:17-172: 4 setup steps (schema → create → store credentials → point provider at URL) + Updating-an-endpoint subsection. The "store credentials before flipping the URL" warning, the Slack ~36-hour auto-disable window, the per-triggerapp_tokenrequirement, the re-handshake-rejection security note, and the PATCH-vs-POST update semantics are all intact. - End-to-end flow disambiguation between ingress URL (provider → Composio) and subscription URL (Composio → your app) remains consistent across
triggers.mdx,subscribing-to-events.mdx, andwebhook-verification.mdx. Docs - Check LinksCI is green, confirmed locally too (bun run scripts/validate-links.ts→ 0 errors). But see the new-issue note above — the link checker happens to accept thepostWebhookEndpointsslug today even though the operation page isn't generated.- Minor (not blocking):
requires_webhook_endpoint_setupis still referenced in 2 places (creating-triggers.mdx:19,glossary.mdx:127) but is not on the SDK or OpenAPI yet. PR body tracks the SDK addition as a follow-up; the field is prose-only here so Twoslash isn't affected.
Once postWebhookEndpoints resolves to a real page (either #3238 merges first, or these two links are reverted to the hub URL), the secret-callout claim is reconciled with the OpenAPI, the three absolute URLs are flipped to relative, and the User ID glossary entry is moved above the Webhook entries, this is good to merge. The two @lingalarahul7 review nits are also worth addressing on the way through.
- Branch:
docs/triggers-webhook-endpoints
…bhook Endpoints API pages Apollo split the Webhooks tag into Webhook Subscriptions + Webhook Endpoints, so /reference/api-reference/webhook-subscriptions and /webhook-endpoints are the canonical pages now. Repoint: - glossary, creating-triggers, subscribing-to-events, webhook-verification, and the webhook-subscriptions changelog - delete the orphan /reference/api-reference/webhooks/index.mdx (and its v3 twin) — Apollo's openapi.json no longer routes any operation to the legacy Webhooks tag, but generate-api-index iterates only tags-with-operations, so the orphan never got auto-removed (separate script bug, follow-up) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @anshugarg15's task in 4m 10s —— View job Docs review (re-review on synchronize)Re-applied the docs-reviewer checklist to the latest pushes since my previous review (
Big news: the secret-callout blocker is resolved by the OpenAPI in this branchThis was the highest-impact item I've been flagging across all the previous reviews. The merge from
So the callouts at
|
| File:Line | Current |
|---|---|
docs/content/toolkits/faq/slack.md:50 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint |
docs/content/toolkits/faq/slack.md:62 |
https://docs.composio.dev/docs/troubleshooting/triggers |
docs/content/toolkits/faq/notion.md:43 |
https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#using-the-sdk |
docs/CLAUDE.md rule #10: "Internal links use relative paths, never absolute. The link checker only validates relative links; absolute URLs silently bypass it and rot over time." Strip https://docs.composio.dev from each:
# slack.md:50
-...see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+...see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
# slack.md:62
-See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers).
+See [Triggers troubleshooting](/docs/troubleshooting/triggers).
# notion.md:43
-Continue with [Creating triggers](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#using-the-sdk).
+Continue with [Creating triggers](/docs/setting-up-triggers/creating-triggers#using-the-sdk).2. Glossary alphabetical ordering (Cursor Bugbot)
docs/content/docs/glossary.mdx re-checked: Webhook Endpoint at line 126, Webhook Subscription at line 130, User ID at line 134. U sorts before W and <Glossary> renders entries in source order (no sort, verified in docs/components/glossary.tsx). Move the User ID block (:134-136) above the Webhook Endpoint block (:126).
Also worth addressing in passing — two unaddressed @lingalarahul7 review nits from 2026-05-08:
creating-triggers.mdx:15→ mention this section is webhook-trigger-only so polling-trigger readers know to skipcreating-triggers.mdx:32→ mark "Per-project metering" as "(in future)" since metering isn't shipped yet
Other things I checked and that are fine
- OpenAPI now has the split tags.
Webhook Subscriptions(7 ops) andWebhook Endpoints(5 ops) are tagged separately atdocs/public/openapi.json:16316–17710. Operation pages for all new IDs (postWebhookEndpoints,getWebhookEndpointsByNanoId, etc.) will be auto-generated from these tags at build time. The new-issue note from my prior review (postWebhookEndpoints404) is resolved — the operation now exists in the spec. - Twoslash unaffected. Code samples at
creating-triggers.mdx:181-227printtriggerType.configonly — no field that doesn't exist in the SDK yet. - Walkthrough completeness preserved at
creating-triggers.mdx:17-172: 4 setup steps (schema → create → store credentials → point provider at URL) + Updating-an-endpoint subsection. The "store credentials before flipping the URL" warning, the Slack ~36-hour auto-disable window, the per-triggerapp_tokenrequirement, the re-handshake-rejection security note, and the PATCH-vs-POST update semantics are all still in place. - End-to-end flow disambiguation between ingress URL (provider → Composio) and subscription URL (Composio → your app) remains consistent across
triggers.mdx,subscribing-to-events.mdx, andwebhook-verification.mdx. requires_webhook_endpoint_setupis still prose-only (creating-triggers.mdx:19,glossary.mdx:127). Re-verified absent from the SDK (ts/packages/core/src/types/triggers.types.ts:152-167) and fromdocs/public/openapi.json. Prose-only, so Twoslash isn't affected. PR body tracks the SDK addition as a follow-up. Worth confirming the canonical name (requires_webhook_endpointper the PR body vs.requires_webhook_endpoint_setupin the docs) with whoever owns the SDK addition before merging.- Notion FAQ flow at
notion.md:17-43correctly models Notion's reverse-verification flow (POST endpoint → paste URL → token arrives → paste back). Asymmetry vs. Slack is called out up front. No factual issues.
With the masked-secret blocker now resolved by the spec update, the only remaining items are the three absolute URLs and the glossary ordering. Once those are flipped, this is good to merge.
- Branch:
docs/triggers-webhook-endpoints
2 participants
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:
requires_webhook_endpointflag is trueDiscovery is at the trigger level. When you inspect a trigger type with
composio.triggers.get_type(), the response includes arequires_webhook_endpointflag. 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 a400if 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/...)docs/triggers.mdxdocs/setting-up-triggers/creating-triggers.mdxrequires_webhook_endpoint/requiresWebhookEndpointalongsideconfigso the discovery moment is visible in-line.docs/setting-up-triggers/subscribing-to-events.mdxdocs/webhook-verification.mdxdocs/troubleshooting/triggers.mdxdocs/glossary.mdxdocs/setting-up-triggers/meta.jsoncreating-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 iscontent/toolkits/faq/{slug}.md— plain markdown rendered as a FAQ accordion at the bottom of the toolkit page.content/toolkits/faq/slack.md/trigger_instances/slack/default/handleURL. Replace with the webhook_endpoints flow (POST endpoint → PATCH signing secret → optionalapp_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.mdBoth FAQ entries link to
/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpointfor the canonical reference.What's deliberately NOT in this PR
/docs/changelog/2026/04/27for historical reference.creating-triggers.mdxso readers don't context-switch mid-flow./reference/api-reference/webhooks/are auto-generated by thedocs-update-dataworkflow from Apollo's OpenAPI export — see Companion PR.Companion PR — must merge with this one
#3238 — docs/auto-update-data is the auto-update PR (open since 2026-04-18). It contains the regenerated
webhooks/index.mdxand the latestopenapi.json, both of which include the newwebhook_endpointsCRUD operations. That PR is what surfaces the API reference pages (postWebhookEndpoints,getWebhookEndpoints,getWebhookEndpointsByNanoId,postWebhookEndpointsByNanoId,patchWebhookEndpointsByNanoId).Verified the auto-PR is correct:
docs/auto-update-data, force-pushed every cycle (every 5 hours) bypeter-evans/create-pull-request.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,704lines come fromopenapi.json(~31k lines) andtoolkits.json(~6.7k lines) being fully regenerated. Review by file list, not by line count.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)
requires_webhook_endpointflag 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 intriggers.mdx, two places increating-triggers.mdx's code samples, plus the cross-references insubscribing-to-events.mdx,webhook-verification.mdx,troubleshooting/triggers.mdx, andglossary.mdx).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 theWebhookstag, markedx-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
bun x fumadocs-mdx && bun run scripts/validate-links.ts— 0 errors after each commit/docs/triggersreads 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/slackand/toolkits/notionFAQ accordions show the new webhook setup stepsrequires_webhook_endpointflag references read correctly across all the trigger pages🤖 Generated with Claude Code