Overview
Webhooks notify your server when Request Network processes a payment, completes KYT screening, or finishes hosted onboarding. Every delivery is an HMAC-signedPOST 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:Manage platform endpoints
All endpoints acceptx-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 toPOST /v1/webhook:
Orchestrator webhooks
Orchestrator webhooks are owned by your orchestrator. Register and manage them withx-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:
client_id.linkedafter the platform completes hosted onboarding.payment.confirmed,kyt.screening.completed, andsecure_payment.user_eventfor Secure Payments the orchestrator created on a linked platformβs behalf.
Register an endpoint
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: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: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 thex-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 includeclientId. 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.
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.- Express.js
- Next.js
Testing
Test deliveries
Fire a test webhook from the Auth API:x-request-network-test: true header so handlers can branch on test vs real.
Test Webhook Identification
Test webhooks include thex-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/webhookat creation - Ensure youβre using the raw request body for signature calculation
- Verify HMAC SHA-256 implementation
- Confirm endpoint URL is accessible via HTTPS
- Verify endpoint returns 2xx status codes
- Confirm the webhook is
activeviaGET /v1/webhook(toggle withPUT /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
Related Documentation
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