Webhooks & Events

Real-time notifications for payments, transaction screening, and hosted onboarding

Overview

Webhooks provide real-time notifications when payment, transaction-screening, and hosted-onboarding events occur, enabling immediate response to status changes without constant polling. Depending on the event, Request Network can deliver a notification to a platform’s Client ID, its linked orchestrator, or both. See the Webhooks reference for recipient routing and the complete technical contract.

Event Categories

The current webhook catalog includes these events:

Category	Events
Hosted onboarding	client_id.linked
Payment	payment.confirmed, payment.failed
Transaction screening	kyt.screening.completed
Secure Payment Page (payer funnel)	secure_payment.user_event (with userEvent)
Secure Payment (payer-wallet allowlist)	secure_payment.access_rejected

For events retained for older API integrations, see Legacy integrations.

Payment webhook 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. See the Webhooks reference for the full payload schema.

For delivery headers and currently documented payload examples, see the Webhooks reference.

How It Works

Process:

1. Event occurs: Payment confirmed, KYT screening completed, or hosted onboarding finished
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
• Failure handling: Detect unsuccessful payment attempts with payment.failed
• Payer-funnel 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

Implementation

Webhook Reference

Endpoint setup, recipient routing, and payloads.

Implementation Examples

Working webhook handlers with Express.js

Auth API webhook endpoints

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

Orchestrator webhooks

Register and test an endpoint with an x-orchestrator-key.