> ## Documentation Index
> Fetch the complete documentation index at: https://requestnetwork-fix-req-350-remove-unused-webhook-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestrator webhooks

> Receive signed notifications when a platform completes hosted onboarding or a transaction screening decision is reached.

## Overview

Orchestrator webhooks notify you about [hosted onboarding](/orchestrators/client-id-linking#onboard-a-platform-with-a-link-intent) and [transaction screening](/orchestrators/kyt-plans). 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

Register an endpoint with your orchestrator key:

```bash theme={null}
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:

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

<Warning>
  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.
</Warning>

Verify the `x-request-network-signature` HMAC-SHA256 header against the raw request body before you process an event. See the [webhook reconciliation guide](/use-cases/webhook-reconciliation) 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`:

```bash theme={null}
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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```bash theme={null}
curl "https://api.request.network/v2/orchestrators/webhooks" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

## Related

<CardGroup cols={3}>
  <Card title="Client ID linking" href="/orchestrators/client-id-linking" icon="link">
    Create a hosted onboarding link and receive its result through a webhook.
  </Card>

  <Card title="Webhook reconciliation" href="/use-cases/webhook-reconciliation" icon="check-double">
    Verify signatures and process webhook deliveries safely.
  </Card>

  <Card title="Orchestrator KYT plans" href="/orchestrators/kyt-plans" icon="shield-halved">
    Configure screening and receive its result.
  </Card>
</CardGroup>