Orchestrator webhooks

Overview

Orchestrator webhooks notify you about hosted onboarding and transaction screening. They are owned by your orchestrator and use your x-orchestrator-key, not a platform’s x-client-id. Register a webhook before you send an onboarding URL to a platform. Its active endpoints receive:

client_id.linked after the platform completes hosted onboarding.
kyt.screening.completed after an orchestrator-linked payment reaches a definitive screening result.

Register a webhook

curl -X POST "https://api.request.network/v2/orchestrators/webhooks" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://partner.example.com/webhooks/request-network" }'

The response includes the webhook and a signing secret:

{
  "webhook": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "url": "https://partner.example.com/webhooks/request-network",
    "isActive": true,
    "createdAt": "2026-08-14T10:00:00.000Z"
  },
  "secret": "4f2c5a8d1b3e6f709c2d4a7b0e1f3c5d8a2b4e6f9c1d3a5b7e0f2c4d6a8b1e3f"
}

Save the signing secret when you register the webhook. Request Network returns it only once and never includes it in list, deactivate, or reactivate responses.

Verify the x-request-network-signature HMAC-SHA256 header against the raw request body before you process an event. See the webhook reconciliation guide for a signature-verifying handler. Webhook deliveries may be retried. Make sure your endpoint can safely receive the same notification more than once.

Test your endpoint

Send a signed mock event to every active endpoint. This example tests client_id.linked:

curl -X POST "https://api.request.network/v2/orchestrators/webhooks/test" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventType": "client_id.linked" }'

The response reports the delivery result:

{
  "sent": 1,
  "failed": 0
}

Test deliveries have the x-request-network-test: true header. They use the same signing process and payload shape as a real event, with placeholder values.

Receive `client_id.linked`

client_id.linked is sent after a platform completes hosted onboarding from a link intent. It is not sent for a direct POST /v2/orchestrators/client-ids link.

{
  "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 your optional externalId to match the event to your onboarding record, then save the returned clientId. Use the stable linkId or intentId to identify a repeated delivery. The destinationId, wallet address, chain, and currency identify the payment destination that the hosted flow bound to the new client ID. Use that client ID with paired authentication to create payment links for the platform.

Receive `kyt.screening.completed`

kyt.screening.completed is sent to active orchestrator webhooks after an orchestrator-linked payment has a definitive approved or rejected screening result. It is not sent for a provider error. When an orchestrator-controlled plan has a backup provider, Request Network tries that backup after a technical failure before deciding whether screening completed.

{
  "event": "kyt.screening.completed",
  "paymentToken": "01KYM5CZ51K0N1KJ4F8S73BE3N",
  "walletAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
  "eoaAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
  "smartAccountAddress": null,
  "status": "approved",
  "provider": "hypernative",
  "policyId": "11111111-1111-4111-8111-111111111111",
  "timestamp": "2026-08-14T10:00:00.000Z"
}

Field	Description
`paymentToken`	The secure-payment token whose screening result completed.
`walletAddress`	The wallet evaluated for this payment.
`eoaAddress`	The connected externally owned account, when available.
`smartAccountAddress`	The connected smart-account address, when available; otherwise `null`.
`status`	`approved` or `rejected`.
`provider`	The provider that produced the definitive result. This can be the backup provider.
`policyId`	The provider policy used, or `null` when the provider account default was used.
`timestamp`	When Request Network evaluated the result.

To test this payload shape, send { "eventType": "kyt.screening.completed" } to POST /v2/orchestrators/webhooks/test. Test deliveries use placeholder values and do not confirm which provider or policy a real payment would use.

Manage webhook endpoints

List every endpoint registered to your orchestrator, including inactive ones:

curl "https://api.request.network/v2/orchestrators/webhooks" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"

{
  "webhooks": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "url": "https://partner.example.com/webhooks/request-network",
      "isActive": true,
      "createdAt": "2026-08-14T10:00:00.000Z"
    }
  ]
}

To stop delivery without removing the endpoint, deactivate it:

curl -X DELETE "https://api.request.network/v2/orchestrators/webhooks/01ARZ3NDEKTSV4RRFFQ69G5FAV" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"

To resume delivery, reactivate the same endpoint:

curl -X PATCH "https://api.request.network/v2/orchestrators/webhooks/01ARZ3NDEKTSV4RRFFQ69G5FAV" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"

Deactivation preserves the endpoint URL and signing secret. Registering the same URL again is rejected, even while it is inactive; reactivate it instead. To use a different URL, deactivate the old endpoint and register the new one.

Client ID linking

Create a hosted onboarding link and receive its result through a webhook.

Webhook reconciliation

Verify signatures and process webhook deliveries safely.

Orchestrator KYT plans

Configure screening and receive its result.

🔑 API Setup

⚙️ API Features

📚 API Reference

Overview

Register a webhook

Test your endpoint

Receive `client_id.linked`

Receive `kyt.screening.completed`

Manage webhook endpoints

Client ID linking

Webhook reconciliation

Orchestrator KYT plans

​Overview

​Register a webhook

​Test your endpoint

​Receive client_id.linked

​Receive kyt.screening.completed

​Manage webhook endpoints

​Related

Client ID linking

Webhook reconciliation

Orchestrator KYT plans

Overview

Register a webhook

Test your endpoint

Receive `client_id.linked`

Receive `kyt.screening.completed`

Manage webhook endpoints

Related