chore: document current webhook delivery

[MantisClone]

Problem

The webhook reference mixes current Secure Payment and orchestrator events with older API-only events. It does not clearly show whether an event reaches a platform's Client ID, its linked orchestrator, or both, or how payload identity fields are populated.

REQ-420

Proposed Solution

• Explain platform and orchestrator endpoint registration, authentication, and recipients.
• Add the current event catalog with recipient routing and identity fields in its payload examples.
• Move older API-only events into an explicit Legacy integrations section.
• Align the Webhooks & Events and orchestrator pages with the canonical reference.

Design Rationale

The API reference is the technical contract for webhook registration, routing, and payloads. The other pages summarize it and link back instead of maintaining separate event catalogs.

Considerations

• This stacks on #130 and does not change navigation or the reconciliation and Quickstart pages.
• It documents the API behavior in request-api#1155, #1156, #1158, and #1159, which are merged into staging. The docs should merge only after those behaviors are part of the public API release.
• payment.failed and secure_payment.access_rejected remain Client-ID-only. client_id.linked remains a hosted-onboarding event.

UAT

1. Open the Webhooks preview. Confirm the current event table identifies the platform's Client ID, linked orchestrator, or both for every event.
2. In the same preview, inspect the payment.confirmed, kyt.screening.completed, secure_payment.user_event, and secure_payment.access_rejected examples. They should show clientId and orchestratorId for an orchestrated Secure Payment.
3. Open Webhooks & Events and Orchestrators overview. They should summarize current events and link to the reference without presenting the legacy events as current flows.

[MantisClone]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore: streamline quickstart webhook guidance #134
• chore: streamline webhook reconciliation guide #133
• chore: document current webhook delivery #132 👈 (View in Graphite)
• chore: consolidate webhook guidance #130
• 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 reorganizes webhook documentation around current Secure Payment, KYT, hosted-onboarding, and orchestrator delivery behavior.

• Adds a recipient matrix distinguishing Client ID and linked-orchestrator deliveries.
• Documents identity fields in current webhook payload examples.
• Separates legacy API-only events from current integration flows.
• Aligns the feature overview, orchestrator overview, and payer-wallet guidance with the canonical webhook reference.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
api-reference/webhooks.mdx	Defines role-specific registration, recipient routing, current event payload identities, and a separate legacy-event catalog.
api-features/webhooks-events.mdx	Reframes the feature overview around current webhook categories and delegates detailed routing to the canonical reference.
orchestrators/overview.mdx	Expands the orchestrator overview to include payment and payer-activity notifications.
use-cases/restrict-payer-wallets.mdx	Clarifies that access-rejection events reach Client ID endpoints, including existing platform-wide registrations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  E[Webhook event] --> T{Event type}
  T -->|client_id.linked| O[Linked orchestrator endpoint]
  T -->|payment.confirmed / KYT completed / user event| B[Client ID and linked orchestrator endpoints]
  T -->|payment.failed / access rejected| C[Client ID endpoint]
  B --> S[Each registration verifies with its own signing secret]
  C --> S
  O --> S

Loading

_{Reviews (3): Last reviewed commit: "chore: document current webhook delivery" | Re-trigger Greptile}

[MantisClone]

@greptile-apps The credentials and callback hosts deliberately use explicit placeholders: every Client ID and callback URL is account-specific, and an orchestrator key is a secret. The examples retain the required cli_ / orc_ prefixes and valid example.com URL shape, without presenting an unusable value as real.

[greptile-apps]

That makes sense. Since the Client ID, callback URL, and orchestrator key are account-specific or secret, explicit placeholders are the safer choice. Retaining the cli_/orc_ prefixes and a valid example.com URL shape communicates the required format without implying that the values are usable credentials. I don’t consider this an issue.

[MantisClone]

@greptile-apps Please refresh the review for the current head (ff1fc71); the placeholder point is resolved by the decision above.