Webhooks & Events

Real-time notifications for Secure Payment, KYT screening, and hosted onboarding events.

Overview

Webhooks notify your server when Request Network processes a Secure Payment, completes KYT screening, or finishes hosted onboarding. The Webhooks reference is the canonical guide for endpoint setup, recipients, and payloads.

Event categories

Current Secure Payment and orchestrator integrations use these events:

Category	Events
Payment	payment.confirmed, payment.failed
KYT screening	kyt.screening.completed
Secure Payment Page	secure_payment.user_event
Payer-wallet allowlist	secure_payment.access_rejected
Hosted onboarding	client_id.linked — a platform completes onboarding to link its Client ID to an orchestrator

The platform’s Client ID and a linked orchestrator do not receive the same events. See the current webhook event catalog for the recipient of each event and its authentication.

Legacy integrations

payment.partial, payment.refunded, payment.processing, compliance.updated, payment_detail.updated, and request.recurring remain available for existing API integrations. They do not apply to current Dashboard, Secure Payment Page, or orchestrator workflows. See Legacy integrations.

Payment payloads include payerAddress, the address used to make the payment, and payerEoaAddress, the payer’s connected wallet address. These can differ when a smart account is used. Both are null when unavailable. Payloads from Secure Payments created with a Client ID include clientId; orchestrated payments also include orchestratorId.

For full payload schemas and headers, see the Webhooks reference.

How It Works

Process:

1. Event occurs: Payment confirmed, KYT screening completes, or hosted onboarding finishes
2. Secure delivery: HMAC SHA-256 signed POST to your configured endpoint
3. Your processing: Verify x-request-network-signature, update application state
4. Reliable delivery: 3 retries (1s, 5s, 15s delays) with 5-second timeout

Key Features

Reliability

• Idempotency support: Use x-request-network-delivery header for duplicate detection
• Delivery confirmation: Monitor x-request-network-retry-count header to track attempts

Security

• HMAC SHA-256 signatures: Every webhook includes x-request-network-signature header
• HTTPS required: Production endpoints must use secure connections
• Test webhook identification: x-request-network-test header for development

Development Tools

• Test deliveries: Use the relevant platform or orchestrator test endpoint. See the Webhooks reference.
• ngrok integration: Receive webhooks locally during development
• Comprehensive logging: Request API logs all delivery failures with attempt details

Common Use Cases

• Invoice systems: Automatically mark invoices as paid when payment.confirmed received
• Order fulfillment: Release goods or services immediately after payment confirmation
• Failed-payment handling: Respond to payment.failed when payment execution fails
• KYT workflows: Respond to approved or rejected kyt.screening.completed results
• User-event visibility: Track wallet connection and signature progress on the Secure Payment Page via secure_payment.user_event
• Payer-wallet monitoring: Detect attempts by wallets that are not allowed to pay via secure_payment.access_rejected
• Hosted onboarding: Complete a platform’s onboarding to your orchestrator after client_id.linked

Implementation

Webhook Reference

Complete technical documentation with setup, payloads, and code examples

Implementation Examples

Working webhook handlers with Express.js and Next.js

Auth API webhook endpoints

POST /v1/webhook to create, GET/PUT/DELETE to manage, /test to fire test deliveries