chore: consolidate webhook guidance

[MantisClone]

Problem

Orchestrator webhook guidance is separate from the main technical reference, so integrators cannot see platform and orchestrator registration, recipient routing, and payload identities in one place. Several pages also present legacy API paths as current webhook integrations.

REQ-420

Proposed Solution

• Consolidate the Webhooks reference into one guide for platform and orchestrator endpoint registration and delivery routing.
• Redirect the previous Orchestrator webhooks page to that reference and update orchestrator links.
• Make the orchestrator path explicit from the overview, hosted-onboarding guide, and reconciliation guide; clarify that endpoint management uses the orchestrator key alone, while payment creation uses paired authentication.
• Lead with current Secure Payment and orchestrator events, then place older API paths in a Legacy integrations section.

Considerations

• The current client_id.linked and kyt.screening.completed payload examples shipped in REQ-455.
• chore: add webhook payload examples #131 and fix: remove unused webhook event variants #129 are merged into main; this PR is now based on main.
• This documentation reflects the pending API contracts in request-api#1155, request-api#1156, request-api#1158, and request-api#1159. It should not merge before the corresponding API behavior ships.
• payment.failed and secure_payment.access_rejected remain platform-only today. payment.partial, payment.refunded, crypto-to-fiat events, and request.recurring remain documented only for legacy API integrations.

UAT

1. Open the preview Webhooks reference and confirm that it distinguishes platform and orchestrator endpoint registration.
2. Confirm that the current catalog leads with client_id.linked, payment.confirmed, payment.failed, kyt.screening.completed, secure_payment.user_event, and secure_payment.access_rejected.
3. Confirm that partial payments, refunds, crypto-to-fiat events, compliance/bank updates, and recurring requests appear only in Legacy integrations.
4. Open /orchestrators/overview and /orchestrators/client-id-linking; their Webhooks links should lead to the orchestrator registration section.
5. Open /use-cases/webhook-reconciliation and confirm that it gives orchestrators the correct setup path and current handler cases.
6. Open /orchestrators/webhooks; it redirects to the canonical guide.

[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}