chore: consolidate webhook guidance

api-features/webhooks-events.mdx

@@ -1,30 +1,31 @@
 ---
 title: "Webhooks & Events"
-description: "Real-time notifications for payment lifecycle events and request status changes"
+description: "Real-time notifications for payments, transaction screening, and hosted onboarding"
 ---
 
 ## Overview
 
-Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without constant polling.
+Webhooks provide real-time notifications when payment, transaction-screening, and hosted-onboarding events occur, enabling immediate response to status changes without constant polling. Depending on the event, Request Network can deliver a notification to a platform's Client ID, its linked orchestrator, or both. See the [Webhooks reference](/api-reference/webhooks#current-webhook-events) for recipient routing and the complete technical contract.
 
 ## Event Categories
 
-The platform and Client ID webhook catalog includes **10 event types** across six categories:
+The current webhook catalog includes these events:
 
 | Category | Events |
 | --- | --- |
-| **Payment** (core) | `payment.confirmed`, `payment.partial`, `payment.failed`, `payment.refunded` |
-| **Processing** (crypto-to-fiat) | `payment.processing` (with `subStatus`) |
-| **Request** | `request.recurring` |
-| **Compliance / Bank** | `compliance.updated`, `payment_detail.updated` |
+| **Hosted onboarding** | `client_id.linked` |
+| **Payment** | `payment.confirmed`, `payment.failed` |
+| **Transaction screening** | `kyt.screening.completed` |
 | **Secure Payment Page** (payer funnel) | `secure_payment.user_event` (with `userEvent`) |
 | **Secure Payment** (payer-wallet allowlist) | `secure_payment.access_rejected` |
 
+For events retained for older API integrations, see [Legacy integrations](/api-reference/webhooks#legacy-integrations).
+
 <Note>
 Payment webhook payloads include `payerAddress`, the address used to make the payment, and `payerEoaAddress`, the payer's connected wallet address. These can differ when a smart account is used. Both are `null` when unavailable. See the [Webhooks reference](/api-reference/webhooks) for the full payload schema.
 </Note>
 
-For full payload schemas and headers, see the [Webhooks reference](/api-reference/webhooks).
+For delivery headers and currently documented payload examples, see the [Webhooks reference](/api-reference/webhooks).
 
 ## How It Works
 
@@ -37,7 +38,7 @@
 ```
 
 **Process:**
-1. **Event occurs:** Payment confirmed, request created, compliance updated
+1. **Event occurs:** Payment confirmed, KYT screening completed, or hosted onboarding finished
 2. **Secure delivery:** HMAC SHA-256 signed POST to your configured endpoint
 3. **Your processing:** Verify `x-request-network-signature`, update application state
 4. **Reliable delivery:** 3 retries (1s, 5s, 15s delays) with 5-second timeout
@@ -45,7 +46,7 @@
 ## Key Features
 
 ### Reliability
 - **Idempotency support:** Use `x-request-network-delivery` header for duplicate detection
 - **Delivery confirmation:** Monitor `x-request-network-retry-count` header to track attempts
 
 ### Security
@@ -54,32 +55,34 @@
 - **Test webhook identification:** `x-request-network-test` header for development
 
 ### Development Tools
-- **Test deliveries:** Fire test events via `POST /v1/webhook/test` (Auth API) — see [Webhooks reference](/api-reference/webhooks#testing)
+- **Test deliveries:** Use the relevant platform or orchestrator test endpoint — see the [Webhooks reference](/api-reference/webhooks)
 - **ngrok integration:** Receive webhooks locally during development
 - **Comprehensive logging:** Request API logs all delivery failures with attempt details
 
 ## Common Use Cases
 
 - **Invoice systems:** Automatically mark invoices as paid when `payment.confirmed` received
 - **Order fulfillment:** Release goods or services immediately after payment confirmation
-- **Subscription management:** Handle `request.recurring` for automatic billing renewals
-- **Compliance workflows:** Update user permissions when `compliance.updated` shows KYC approval
-- **Real-time dashboards:** Display live payment status using `payment.processing` subStatus values
+- **Failure handling:** Detect unsuccessful payment attempts with `payment.failed`
 - **Payer-funnel visibility:** Track wallet connection and signature progress on the Secure Payment Page via `secure_payment.user_event`
 - **Payer-wallet monitoring:** Detect attempts by wallets that are not allowed to pay via `secure_payment.access_rejected`
 
 ## Implementation
 
 <CardGroup cols={2}>
-  <Card title="Webhook Reference" href="/api-reference/webhooks">
-    Complete technical documentation with setup, payloads, and code examples
+  <Card title="Webhook Reference" href="/api-reference/webhooks" icon="webhook">
+    Endpoint setup, recipient routing, and payloads.
   </Card>
 
-  <Card title="Implementation Examples" href="/api-reference/webhooks">
-    Working webhook handlers with Express.js and Next.js
+  <Card title="Implementation Examples" href="/use-cases/webhook-reconciliation">
+    Working webhook handlers with Express.js
   </Card>
 
   <Card title="Auth API webhook endpoints" href="https://auth.request.network/open-api/#tag/webhook" icon="webhook">
     POST /v1/webhook to create, GET/PUT/DELETE to manage, /test to fire test deliveries
   </Card>
+
+  <Card title="Orchestrator webhooks" href="/api-reference/webhooks#register-an-orchestrator-webhook" icon="webhook">
+    Register and test an endpoint with an `x-orchestrator-key`.
+  </Card>
 </CardGroup>