From ce83df5e26c133cbd192405ed1a2686669941a4a Mon Sep 17 00:00:00 2001
From: MantisClone <david.huntmateo@request.network>
Date: Tue, 25 Aug 2026 18:26:35 +0200
Subject: [PATCH] chore: add webhook payload examples

---
 api-reference/webhooks.mdx | 44 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx
index 510d8bc..85f7d70 100644
--- a/api-reference/webhooks.mdx
+++ b/api-reference/webhooks.mdx
@@ -232,6 +232,30 @@ All payment events include an `explorer` field linking to [Request Scan](https:/
 - `payerAddress`: Resolved payer wallet — the on-chain sender for plain direct payments, or the resolved payer for recurring and intent-based flows (Secure Payment Page, LiFi, Safe, ERC-4337, multicall). `null` when it cannot be determined. Included on `payment.confirmed` and `payment.partial` events (and their `.client_id` / `.checkout` variants).
 - `payerEoaAddress`: The payer's connected wallet address. It can differ from `payerAddress` when a smart account is used. `null` when unavailable. Included on `payment.confirmed` and `payment.partial` events (and their `.client_id` / `.checkout` variants).
 
+The `client_id.linked` and `kyt.screening.completed` examples below are delivered to an orchestrator endpoint. Register that endpoint with `x-orchestrator-key` as described in [Orchestrator webhooks](/orchestrators/webhooks).
+
+### Client ID linked
+
+`client_id.linked` is sent to an orchestrator after a platform completes hosted onboarding from a link intent.
+
+```json
+{
+  "event": "client_id.linked",
+  "clientId": "cli_PLATFORM_CLIENT_ID",
+  "orchestratorId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
+  "linkId": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
+  "intentId": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
+  "externalId": "merchant_123",
+  "destinationId": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e@eip155:8453#B4FD67BB:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+  "destinationWalletAddress": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
+  "chain": "base",
+  "currency": "USDC",
+  "timestamp": "2026-08-14T10:00:00.000Z"
+}
+```
+
+Use `intentId` or `externalId` to match this event to your onboarding record. Use `linkId` or `intentId` to identify a repeated delivery.
+
 ### Payment Confirmed
 ```json
 {
@@ -334,6 +358,26 @@ All payment events include an `explorer` field linking to [Request Scan](https:/
 }
 ```
 
+### KYT Screening Completed
+
+`kyt.screening.completed` is sent after an orchestrator-linked payment reaches an `approved` or `rejected` screening result.
+
+```json
+{
+  "event": "kyt.screening.completed",
+  "paymentToken": "01KYM5CZ51K0N1KJ4F8S73BE3N",
+  "walletAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
+  "eoaAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
+  "smartAccountAddress": null,
+  "status": "approved",
+  "provider": "hypernative",
+  "policyId": "11111111-1111-4111-8111-811111111111",
+  "timestamp": "2026-08-14T10:00:00.000Z"
+}
+```
+
+`provider` is the provider that produced the result. `policyId` is `null` when the provider account default was used.
+
 ### Secure Payment User Event
 ```json
 {