Webhooks

Overview

Webhooks notify your server when Request Network processes a payment, completes KYT screening, or finishes hosted onboarding. Every delivery is an HMAC-signed POST request. A platform owns its Client IDs and Secure Payments. When it links a Client ID to an orchestrator, the orchestrator can create Secure Payments on the platform’s behalf. Some events are then delivered to both the platform’s Client ID endpoint and the linked orchestrator’s endpoint. You do not subscribe an endpoint to individual event types. An active endpoint receives the events available to the Client ID or orchestrator that registered it.

New platform endpoints are scoped to a Client ID. Existing platform-wide endpoints continue to receive their platform events, but you cannot create new platform-wide endpoints through the current registration flow.

Choose who receives notifications

Recipient	Authentication	Receives
Platform’s Client ID	`x-client-id` or the platform’s Dashboard session	Events for Secure Payments created with that Client ID.
Orchestrator	`x-orchestrator-key`	Hosted-onboarding events and events for Secure Payments it created on behalf of a linked platform.

Register each role separately, even if both roles use the same callback URL. Each registration has its own signing secret.

Orchestrator integration: Registering and managing an orchestrator endpoint requires only x-orchestrator-key. Use paired x-client-id and x-orchestrator-key authentication only when you create a Secure Payment for a linked platform.

Register a platform Client ID webhook

Use the platform’s Client ID to register an endpoint:

curl -X POST "https://auth.request.network/v1/webhook" \
  -H "Content-Type: application/json" \
  -H "x-client-id: cli_YOUR_CLIENT_ID" \
  -d '{ "url": "https://platform.example.com/webhooks/request-network" }'

Response (201 Created):

{
  "id": "01KJC2WX8EH4MP3DHZB2YQ7N9G",
  "secret": "f3c189a4b5e6d7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
}

Save secret when you create the endpoint. Request Network returns it only once. Use HTTPS in production; localhost is accepted for local development.

If you use a Dashboard session instead of x-client-id, include the Client ID in the request body when creating or testing an endpoint. See the Auth API webhook endpoints for that session-authenticated form.

Manage and test platform endpoints

Method	Path	Purpose
`GET`	`/v1/webhook`	List the Client ID’s endpoints.
`PUT`	`/v1/webhook/:webhookId`	Activate or deactivate an endpoint.
`DELETE`	`/v1/webhook/:webhookId`	Permanently remove an endpoint.
`POST`	`/v1/webhook/test`	Send a signed test event to active endpoints.

Test a platform endpoint with the same Client ID:

curl -X POST "https://auth.request.network/v1/webhook/test" \
  -H "Content-Type: application/json" \
  -H "x-client-id: cli_YOUR_CLIENT_ID" \
  -d '{ "eventType": "payment.confirmed" }'

Test deliveries include x-request-network-test: true. They use the same signature format and an example payload; they do not represent a real payment or screening decision.

Register an orchestrator webhook

Use the orchestrator key to register an endpoint:

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://orchestrator.example.com/webhooks/request-network" }'

Response (201 Created):

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

Save secret when you register the endpoint. Request Network never includes it in list, deactivate, or reactivate responses.

Manage and test orchestrator endpoints

Method	Path	Purpose
`GET`	`/v2/orchestrators/webhooks`	List the orchestrator’s endpoints, including inactive endpoints.
`DELETE`	`/v2/orchestrators/webhooks/:id`	Deactivate an endpoint without removing its URL or signing secret.
`PATCH`	`/v2/orchestrators/webhooks/:id`	Reactivate an endpoint.
`POST`	`/v2/orchestrators/webhooks/test`	Send a signed test event to every active endpoint.

To test an orchestrator endpoint:

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" }'

Deactivation preserves the endpoint. Registering the same URL again is rejected, including while it is inactive; reactivate it instead. To change the URL, deactivate the old endpoint and register the new one.

Current webhook events

These are the events for current Secure Payment and orchestrator integrations. The platform’s Client ID also receives payment.confirmed, KYT, and payer-activity events for Secure Payments created by its linked orchestrator.

Event	Platform’s Client ID	Linked orchestrator	Notes
`client_id.linked`	No	Yes	Sent after hosted onboarding completes. Direct API links do not emit this event.
`payment.confirmed`	Yes	Yes	Both receive it when the linked orchestrator created the Secure Payment for the platform.
`payment.failed`	Yes	No	Payment execution fails.
`kyt.screening.completed`	Yes	Yes	Sent after a definitive `approved` or `rejected` result. Provider errors do not emit it.
`secure_payment.user_event`	Yes	Yes	Best-effort payer activity from the Secure Payment Page. Do not use it as a settlement signal.
`secure_payment.access_rejected`	Yes	No	A wallet outside an incoming payment’s payer-wallet allowlist tries to access or pay it.

payment.confirmed is the settlement signal. secure_payment.user_event is browser-reported activity: navigation, network failures, or browser extensions can prevent Request Network from receiving it. Its absence does not prove that the payer did not take that step.

Payload identity and correlation

For a Secure Payment created with a Client ID, payloads identify the platform’s Client ID with clientId. When the payment was created through an orchestrator, they also include orchestratorId. orchestratorId is the orchestrator recorded when the Secure Payment was created. A later link, unlink, or relink does not change past payment events. Use requestId, paymentToken, or securePaymentToken to correlate the event with your own records. Payment events include an explorer URL for Request Scan when one is available. requestId and requestID identify the request, and paymentReference is its short unique reference.

Hosted onboarding completed

client_id.linked lets the orchestrator match hosted onboarding to the link intent it created. Use linkId or intentId to deduplicate repeated deliveries.

{
  "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"
}

Payment confirmed

Do not fulfill an order until you receive payment.confirmed.

{
  "event": "payment.confirmed",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "explorer": "https://scan.request.network/request/0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "amount": "100.0",
  "totalAmountPaid": "100.0",
  "expectedAmount": "100.0",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "payerAddress": "0x92Fc3406Fc6BB7A76aC63b2E8b9d02b1B9C3e4d5",
  "payerEoaAddress": "0x7A1F20C4D58E9B0A3C6D4E2F1B8A5C7D9E0F1234",
  "network": "ethereum",
  "currency": "USDC",
  "paymentCurrency": "USDC",
  "fees": [],
  "clientId": "cli_PLATFORM_CLIENT_ID",
  "orchestratorId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "timestamp": "2026-08-14T10:00:00.000Z"
}

payerAddress is the address used to make the payment. payerEoaAddress is the payer’s connected wallet and can differ when a smart account is used. Either can be null when unavailable.

Payment failed

{
  "event": "payment.failed",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "subStatus": "insufficient_funds",
  "paymentProcessor": "request-network"
}

KYT screening completed

KYT results are sent only for definitive approved and rejected outcomes. If an orchestrator-controlled plan has a backup provider, Request Network tries it after a technical provider 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",
  "clientId": "cli_PLATFORM_CLIENT_ID",
  "orchestratorId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "timestamp": "2026-08-14T10:00:00.000Z"
}

Secure Payment user event

secure_payment.user_event reports wallet_connected, payment_sent_to_wallet, or payment_approved_in_wallet. occurredAt and properties come from the payer’s browser; timestamp is added by Request Network when it receives the event.

`userEvent`	Meaning
`wallet_connected`	The payer connected a wallet on the Secure Payment Page.
`payment_sent_to_wallet`	The payment transaction was handed to the payer’s wallet for signature.
`payment_approved_in_wallet`	The payer approved the payment in its wallet. This is not confirmation that it settled on-chain.

{
  "event": "secure_payment.user_event",
  "userEvent": "payment_approved_in_wallet",
  "securePaymentToken": "spt_3fk29ax7...",
  "requestId": "01JD3E6JD46KY4KKV7X9V0MZ7W",
  "requestIds": ["01JD3E6JD46KY4KKV7X9V0MZ7W"],
  "clientId": "cli_PLATFORM_CLIENT_ID",
  "orchestratorId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "occurredAt": "2026-08-05T14:03:21.512Z",
  "timestamp": "2026-08-05T14:03:22.104Z",
  "properties": {
    "wallet_provider": "metamask",
    "payment_submission_id": "0x6a4f...e21b",
    "payment_submission_id_type": "evm_tx_hash",
    "selected_source_chain": "base",
    "payment_type": "single"
  }
}

Payer-wallet access rejected

secure_payment.access_rejected is emitted when a wallet that is not on an incoming payment’s allowedPayerAddresses allowlist tries to access or pay it. It is not a KYT result. Repeated attempts by the same wallet on the same payment are normally suppressed for 10 minutes.

{
  "event": "secure_payment.access_rejected",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "attemptedPayerWalletAddress": "0x2e2e5c79f571ef1658d4c2d3684a1fe97dd30570",
  "clientId": "cli_PLATFORM_CLIENT_ID",
  "orchestratorId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "timestamp": "2026-08-10T10:05:00.000Z"
}

See Restrict payer wallets to configure the allowlist.

Field	Description
`requestId`	The request the wallet tried to access.
`attemptedPayerWalletAddress`	The rejected wallet address. EVM addresses are lowercased; TRON addresses keep their original case.
`timestamp`	When Request Network emitted the event.

Delivery requirements

Verify x-request-network-signature against the raw request body before you parse it. Use x-request-network-delivery as your durable idempotency key: Request Network retries failed deliveries, so the same event can arrive more than once.

Use HTTPS for production endpoints.
Store each endpoint’s signing secret securely; it is returned only when that endpoint is created.
Handle unknown event names safely so a new event does not fail your endpoint.

For an Express handler, local testing with ngrok, and reconciliation patterns, see Webhook reconciliation.

Delivery headers

Header	Description
`x-request-network-signature`	HMAC-SHA256 of the raw JSON body, encoded as hex.
`x-request-network-delivery`	Stable delivery ID. Use it as the idempotency key.
`x-request-network-retry-count`	Current attempt: `0` to `3`.
`x-request-network-test`	`true` for test deliveries only.
`content-type`	`application/json`.

Retry policy

Request Network retries non-2xx responses, timeouts, and connection errors. A delivery has four attempts in total: the initial request plus retries after 1, 5, and 15 seconds. Each attempt has a five-second timeout. Return a 2xx response only after you have safely recorded the delivery. If processing fails, return a non-2xx response so Request Network retries it.

Troubleshooting

Signature verification fails

Verify the signature against the raw request body, not a parsed or re-serialized body.
Confirm that you saved the secret returned when this specific endpoint was created.
Confirm that the endpoint’s platform or orchestrator registration is active.

No webhook arrives

Confirm that the relevant Client ID or orchestrator has an active endpoint.
Confirm that the event belongs to that recipient in Current webhook events.
Send a test event to verify endpoint reachability and signature handling.

Legacy integrations

These events remain available for existing API integrations. They do not apply to current Dashboard, Secure Payment Page, or orchestrator workflows.

Event	Legacy flow
`payment.partial`	Partial-payment flow
`payment.refunded`	Existing refund flows
`payment.processing`	Crypto-to-fiat processing
`compliance.updated`	Crypto-to-fiat compliance updates
`payment_detail.updated`	Crypto-to-fiat bank-detail updates
`request.recurring`	Recurring requests

Webhooks & Events

Learn the event categories and common webhook use cases.

Webhook reconciliation

Implement a signed webhook handler and process events safely.

Client ID linking

Link a platform’s Client ID and receive hosted-onboarding results.

Orchestrator KYT plans

Configure transaction screening for linked platforms.

Restrict payer wallets

Allow only selected payer wallets for an incoming payment.

🔑 API Setup

⚙️ API Features

📚 API Reference

Overview

Choose who receives notifications

Register a platform Client ID webhook

Manage and test platform endpoints

Register an orchestrator webhook

Manage and test orchestrator endpoints

Current webhook events

Payload identity and correlation

Hosted onboarding completed

Payment confirmed

Payment failed

KYT screening completed

Secure Payment user event

Payer-wallet access rejected

Delivery requirements

Delivery headers

Retry policy

Troubleshooting

Legacy integrations

Webhooks & Events

Webhook reconciliation

Client ID linking

Orchestrator KYT plans

Restrict payer wallets

​Overview

​Choose who receives notifications

​Register a platform Client ID webhook

​Manage and test platform endpoints

​Register an orchestrator webhook

​Manage and test orchestrator endpoints

​Current webhook events

​Payload identity and correlation

​Hosted onboarding completed

​Payment confirmed

​Payment failed

​KYT screening completed

​Secure Payment user event

​Payer-wallet access rejected

​Delivery requirements

​Delivery headers

​Retry policy

​Troubleshooting

​Legacy integrations

​Related webhook pages

Webhooks & Events

Webhook reconciliation

​Related

Client ID linking

Orchestrator KYT plans

Restrict payer wallets

Overview

Choose who receives notifications

Register a platform Client ID webhook

Manage and test platform endpoints

Register an orchestrator webhook

Manage and test orchestrator endpoints

Current webhook events

Payload identity and correlation

Hosted onboarding completed

Payment confirmed

Payment failed

KYT screening completed

Secure Payment user event

Payer-wallet access rejected

Delivery requirements

Delivery headers

Retry policy

Troubleshooting

Legacy integrations

Related webhook pages

Related