chore: consolidate webhook guidance

[MantisClone]

Problem

Orchestrator webhook setup is documented separately from the main webhook reference.

This makes an orchestrator switch pages to register, test, and manage an endpoint. The overview, Client ID linking, and KYT plans guides all point to that separate page.

REQ-420

Proposed Solution

• Add orchestrator endpoint setup and management to the Webhooks reference.
• Redirect the former Orchestrator webhooks page to that reference and remove it from navigation.
• Link the relevant orchestrator guides directly to the new section and its payload examples.

Design Rationale

The Webhooks reference is the single technical page for registering and managing endpoints. Keeping orchestrator setup there avoids duplicate instructions while leaving the existing platform webhook guidance unchanged.

Considerations

• This PR covers only the original documentation consolidation. Current routing and delivery behavior, the legacy-event catalog, the reconciliation guide, and the Quickstart cleanup are deliberately deferred to stacked follow-up PRs.
• This PR does not change webhook delivery or payloads.

UAT

1. Open the preview Webhooks reference and confirm that the Orchestrator webhooks section covers registration, testing, listing, deactivation, and reactivation with x-orchestrator-key.
2. Open the Orchestrators overview, Client ID linking, and KYT plans. Their webhook links should lead to the relevant reference section or payload example.
3. Open the former Orchestrator webhooks route; it should redirect to the Webhooks reference.

[MantisClone]

• chore: streamline quickstart webhook guidance #134
• chore: streamline webhook reconciliation guide #133
• chore: document current webhook delivery #132
• chore: consolidate webhook guidance #130 👈 (View in Graphite)
• fix: remove unused webhook event variants #129
• chore: add webhook payload examples #131
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

The PR consolidates orchestrator webhook registration and endpoint-management guidance into the main webhook reference, redirects the former page, and updates orchestrator documentation links.

• Adds orchestrator registration, testing, deactivation, and reactivation instructions.
• Redirects /orchestrators/webhooks to the consolidated reference and removes the old page from navigation.
• Updates overview, Client ID linking, and KYT links to target the consolidated sections and payload examples.

Confidence Score: 3/5

The PR is not yet safe to merge because the canonical Express webhook example still processes test deliveries as real events and invokes undefined business handlers.

The consolidation itself preserves the intended routes and content, but previously reported blocking defects remain in the destination page: checking the test header does not stop placeholder events from reaching business logic, and the copied Express example fails when its undefined handlers are invoked.

Files Needing Attention: api-reference/webhooks.mdx

Important Files Changed

Filename	Overview
api-reference/webhooks.mdx	Consolidates orchestrator webhook guidance successfully, but previously reported defects in the existing Express receiver example remain outstanding.
docs.json	Adds a relevant redirect for the deleted orchestrator webhook page and removes that page from navigation.
orchestrators/client-id-linking.mdx	Updates setup and event links to valid sections of the consolidated webhook reference.
orchestrators/kyt-plans.mdx	Retargets webhook guidance and KYT payload links to valid consolidated-page anchors.
orchestrators/overview.mdx	Updates orchestrator webhook references to the new canonical section.
orchestrators/webhooks.mdx	Removes the superseded standalone page after its guidance is consolidated and redirected.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Old["/orchestrators/webhooks"] -->|redirect| Reference["/api-reference/webhooks"]
  Overview["Orchestrator overview"] --> Reference
  Linking["Client ID linking"] --> Reference
  KYT["KYT plans"] --> Reference
  Reference --> Setup["Registration and endpoint management"]
  Reference --> Payloads["client_id.linked and kyt.screening.completed payloads"]

Loading

_{Reviews (12): Last reviewed commit: "chore: consolidate webhook guidance" | Re-trigger Greptile}