Skip to main content

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.

Choose who receives notifications

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. Register each role separately, even if both roles use the same callback URL. Each registration has its own signing secret.
New platform endpoints are scoped to a Client ID. Existing platform-wide endpoints continue to receive platform events, but you cannot create new platform-wide endpoints through the current registration flow.

Register a platform Client ID webhook

Use the platform’s Client ID to register an endpoint:
Response (201 Created):
Save secret when you create the endpoint. Request Network returns it only once. Use HTTPS in production; localhost is accepted for local development.

Manage platform endpoints

All endpoints accept x-client-id and operate on the webhooks owned by that Client ID. Open the Auth API Scalar docs to call these interactively with your wallet session. Signing in to the Dashboard sets the session cookie shared across Request Network services.

Local Development

Use ngrok to receive webhooks locally, then pass the public URL to POST /v1/webhook:

Orchestrator webhooks

Orchestrator webhooks are owned by your orchestrator. Register and manage them with x-orchestrator-key, not a platform’s x-client-id. Register an endpoint before you send a hosted onboarding URL to a platform. Its active endpoints receive:

Register an endpoint

The response includes the endpoint and a signing secret:
Save the signing secret when you register the endpoint. 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 Signature Verification. Webhook deliveries may be retried, so your endpoint must safely handle the same notification more than once.

Test your endpoint

Send a signed mock event to every active endpoint:
Test deliveries include x-request-network-test: true. They use the same signing process and payload shape as a real event, with placeholder values.

Manage endpoints

List every endpoint registered to your orchestrator, including inactive ones:
To stop delivery without removing the endpoint, deactivate it:
To resume delivery, reactivate the same endpoint:
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.

Current webhook events

These are the events for current Secure Payment and orchestrator integrations. The platform’s Client ID receives the events shown below for Secure Payments created with that Client ID. The userEvent field distinguishes the 3 funnel steps:
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.When the Secure Payment Page includes wallet information in properties, it uses wallet_address_hashed rather than a raw wallet address.

Payer-wallet access rejections

secure_payment.access_rejected is generated server-side when a wallet that is not on an incoming payment’s allowedPayerAddresses allowlist tries to access or pay it. It is not emitted for KYT decisions. It goes to the payment’s Client ID endpoints, including any existing platform-wide endpoint, not to the orchestrator. See Restrict payer wallets to configure the allowlist. Repeated attempts by the same wallet on the same payment are normally suppressed for 10 minutes. If every configured webhook endpoint fails, the next access attempt can trigger another notification.

Security Implementation

Signature Verification

Every webhook includes an HMAC SHA-256 signature in the x-request-network-signature header:

Security Requirements

  • HTTPS only: Production webhooks require HTTPS endpoints
  • Always verify signatures: Never process unverified webhook requests
  • Keep secrets secure: Store signing secrets as environment variables
  • Return 2xx for success: Any 2xx status code confirms successful processing

Request Headers

Each webhook request includes these headers:

Retry Logic

Automatic Retries

  • Max attempts: 3 retries (4 total attempts)
  • Retry delays: 1s, 5s, 15s
  • Trigger conditions: Non-2xx response codes, timeouts, connection errors
  • Timeout: 5 seconds per request

Response Handling

Error Logging

Request API logs all webhook delivery failures with:
  • Endpoint URL
  • Attempt number
  • Error details
  • Final failure after all retries

Payload identity and examples

For a Secure Payment created with a Client ID, payloads include clientId. When it was created through an orchestrator, payloads also include orchestratorId. orchestratorId is the orchestrator recorded when the Secure Payment was created. Linking, unlinking, or relinking that Client ID later does not change historical payment events. Use requestId, paymentToken, or securePaymentToken to correlate an event with your records. Payment events include an explorer field linking to Request Scan when one is available. requestId and requestID identify the request, and paymentReference is its short unique reference. payerAddress is the resolved payer wallet and payerEoaAddress is the payer’s connected wallet. They can differ when a smart account is used. Both are null when unavailable and are included on payment.confirmed and payment.partial events.

Client ID linked

client_id.linked is sent to an orchestrator after a platform completes hosted onboarding from a link intent.
Use intentId or externalId to match this event to your onboarding record. Use linkId or intentId to identify a repeated delivery.

Payment Confirmed

Payment Processing

Payment Partial

Payment Failed

Compliance Updated

KYT Screening Completed

kyt.screening.completed is sent after a Secure Payment reaches an approved or rejected screening result.
provider is the provider that produced the result. policyId is null when the provider account default was used.

Secure Payment User Event

Secure Payment Access Rejected

Use POST /v1/webhook/test with { "eventType": "secure_payment.access_rejected" } to test this event without a rejected access attempt.

Legacy integrations

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

Implementation Examples

For a complete working example, see Webhook reconciliation which implements webhook handling for payment notifications.

Testing

Test deliveries

Fire a test webhook from the Auth API:
Or call it interactively from the Auth API Scalar docs. Test deliveries arrive at all active webhooks for that Client ID and include the x-request-network-test: true header so handlers can branch on test vs real.

Test Webhook Identification

Test webhooks include the x-request-network-test: true header:

Best Practices

Error Handling

  • Implement idempotency: Use delivery IDs to prevent duplicate processing
  • Graceful degradation: Handle unknown event types without errors

Performance

  • Timeout management: Complete processing within 5 seconds

Troubleshooting

Common Issues

Signature verification fails:
  • Check your signing secret matches the value returned by POST /v1/webhook at creation
  • Ensure you’re using the raw request body for signature calculation
  • Verify HMAC SHA-256 implementation
Webhooks not received:
  • Confirm endpoint URL is accessible via HTTPS
  • Verify endpoint returns 2xx status codes
  • Confirm the webhook is active via GET /v1/webhook (toggle with PUT /v1/webhook/:id)

Debugging Tips

  • Use ngrok request inspector to see raw webhook data
  • Monitor retry counts in headers to identify issues
  • Fire test deliveries via POST /v1/webhook/test

Webhooks & Events

High-level webhook concepts and workflow

Webhook reconciliation

Complete webhook implementation example

Authentication

API credential setup and webhook security

Request Dashboard

Manage Client IDs, payment destinations, and webhooks
Last modified on September 1, 2026