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:
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.How It Works
Process:- Event occurs: Payment confirmed, KYT screening completed, or hosted onboarding finished
- Secure delivery: HMAC SHA-256 signed POST to your configured endpoint
- Your processing: Verify
x-request-network-signature, update application state - Reliable delivery: 3 retries (1s, 5s, 15s delays) with 5-second timeout
Key Features
Reliability
- Idempotency support: Use
x-request-network-deliveryheader for duplicate detection - Delivery confirmation: Monitor
x-request-network-retry-countheader to track attempts
Security
- HMAC SHA-256 signatures: Every webhook includes
x-request-network-signatureheader - HTTPS required: Production endpoints must use secure connections
- Test webhook identification:
x-request-network-testheader 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.confirmedreceived - 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.