chore: consolidate webhook guidance

[MantisClone]

Problem

Webhook documentation does not give an orchestrator integrator one clear, current path for registering an endpoint, understanding which events it receives, and reading the payload.

Relevant guidance is split between the main reference and the older Orchestrator page. Legacy API events also appear alongside current Secure Payment and orchestrator events, making it hard to tell what applies to a new integration.

REQ-420

Proposed Solution

• Give platform and orchestrator integrations one technical reference for endpoint setup, event recipients, and payload identities.
• Present current Secure Payment and orchestrator events first, with older API-only events in a separate Legacy integrations section.
• Point the Quickstart and related orchestrator pages to the relevant setup guidance instead of duplicating it.
• Make the required credentials clear: an orchestrator key manages its endpoints; paired authentication creates a Secure Payment for a linked platform.

Design Rationale

• A webhook endpoint receives every event available to its Client ID or orchestrator. There is no per-event subscription setting.
• The former Orchestrator webhooks page redirects to the technical reference so endpoint setup and event routing do not drift between pages.
• The reference keeps platform-only events visible while separating older API integrations from the current Secure Payment and orchestrator path.

Considerations

• mintlify-docs#131 already added the current client_id.linked and kyt.screening.completed payload examples under REQ-455.
• This documentation depends on the pending delivery and identity changes in request-api#1155, request-api#1156, request-api#1158, and request-api#1159. It should merge only after the corresponding API behavior is available.
• This PR documents the current API; it does not change webhook delivery. payment.failed and secure_payment.access_rejected remain platform-only. Partial payments, refunds, crypto-to-fiat events, compliance and bank updates, and recurring requests remain legacy API integrations.

UAT

1. Open the preview Webhooks reference and confirm that it distinguishes platform and orchestrator endpoint setup.
2. Confirm that the current event catalog appears before Legacy integrations, and that legacy-only events are clearly separated.
3. Open the preview Quickstart and confirm that its webhook step links to the reference instead of repeating the setup guide.
4. Open the Orchestrators overview and Client ID linking; their webhook links should lead to the orchestrator setup section.
5. Open /orchestrators/webhooks; it should redirect to the canonical reference.

[MantisClone]

• 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 platform and orchestrator webhook documentation into one canonical reference.

• Adds orchestrator registration, authentication, recipient-routing, and event-contract guidance.
• Redirects the retired orchestrator webhook page and updates related navigation.
• Aligns webhook catalogs, payload identities, test-delivery handling, and settlement guidance.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
api-reference/webhooks.mdx	Consolidates registration, recipient routing, event catalogs, payload identities, delivery requirements, and retry guidance.
use-cases/webhook-reconciliation.mdx	Expands the shared webhook handling flow for platform and orchestrator events and adds safe test-delivery handling.
docs.json	Redirects the retired orchestrator webhook route to the consolidated reference and removes the obsolete navigation entry.
orchestrators/webhooks.mdx	Removes the superseded standalone orchestrator webhook page.
api-features/webhooks-events.mdx	Aligns the overview catalog and routing language with the consolidated webhook reference.

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