Webhooks - Request Network Docs

Overview

Webhooks deliver real-time notifications when payment and request events occur. Configure your endpoints to receive HMAC-signed POST requests with automatic retry logic and comprehensive event data.

Webhook Configuration

Setup in Portal

Navigate to Platform Settings → Webhooks in Request Portal
Click Add webhook
In the dialog that opens, enter URL and click Create webhook
Click copy button to copy Signing Secret to clipboard (see Authentication for API key setup)
Enable/disable or delete webhooks as needed

Local Development

Use ngrok to receive webhooks locally:

ngrok http 3000
# Use the HTTPS URL (e.g., https://abc123.ngrok.io/webhook) in Portal

Event Types

See Payload Examples below for detailed webhook structures.

Payment Events

Event	Description	Context	Primary Use
`payment.confirmed`	Payment fully completed and settled	After blockchain confirmation	Complete fulfillment, release goods
`payment.partial`	Partial payment received for request	Installments, partial orders	Update balance, allow additional payments
`payment.failed`	Payment execution failed	Recurring payments, cross-chain transfers	Notify failure, retry logic, pause subscriptions
`payment.refunded`	Payment has been refunded to payer	Cross-chain payment failures, refund scenarios	Update order status, notify customer

Processing Events

Event	Description	Context	Primary Use
`payment.processing`	Crypto-to-fiat payment in progress	subStatus values: initiated, pending_internal_assessment, ongoing_checks, sending_fiat, fiat_sent, bounced	Track crypto-to-fiat payment status, update UI

Request Events

Event	Description	Context	Primary Use
`request.recurring`	New recurring request generated	Subscription renewals, scheduled payments	Send renewal notifications, update billing

Compliance Events

Event	Description	Context	Primary Use
`compliance.updated`	KYC or agreement status changed	kycStatus values: not_started, pending, approved, rejected, retry_required agreementStatus values: not_started, pending, completed, rejected, failed	Update user permissions, notify status
`payment_detail.updated`	Bank account verification status updated	States: approved, failed, pending	Enable fiat payments, update profiles

Security Implementation

Signature Verification

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

import crypto from "node:crypto";

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  } catch {
    return false;
  }
}

// Usage in your webhook handler
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-request-network-signature"];
  
  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  
  // Parse JSON after verification
  const body = JSON.parse(req.rawBody.toString("utf8"));
  
  // Process webhook...
  res.status(200).json({ success: true });
});

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:

Header	Description	Example
`x-request-network-signature`	HMAC SHA-256 signature	`a1b2c3d4e5f6...`
`x-request-network-delivery`	Unique delivery ID (ULID)	`01ARZ3NDEKTSV4RRFFQ69G5FAV`
`x-request-network-retry-count`	Current retry attempt (0-3)	`0`
`x-request-network-test`	Present for test webhooks	`true`
`content-type`	Always JSON	`application/json`

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

// ✅ Success - no retry
res.status(200).json({ success: true });
res.status(201).json({ created: true });

// ❌ Error - triggers retry
res.status(401).json({ error: "Unauthorized" });
res.status(404).json({ error: "Resource not found" });
res.status(500).json({ error: "Internal server error" });

Error Logging

Request API logs all webhook delivery failures with:

Endpoint URL
Attempt number
Error details
Final failure after all retries

Payload Examples

All payment events include an explorer field linking to Request Scan for transaction details. Common Fields:

requestId / requestID: Unique identifier for the payment request
paymentReference: Short reference, also unique to a request, used to link payments to the request
timestamp: ISO 8601 formatted event timestamp
paymentProcessor: Either request-network (crypto) or request-tech (fiat)

Payment Confirmed

{
  "event": "payment.confirmed",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "explorer": "https://scan.request.network/request/0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "amount": "100.0",
  "totalAmountPaid": "100.0",
  "expectedAmount": "100.0",
  "timestamp": "2025-10-03T14:30:00Z",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "network": "ethereum",
  "currency": "USDC",
  "paymentCurrency": "USDC",
  "isCryptoToFiat": false,
  "subStatus": "",
  "paymentProcessor": "request-network",
  "fees": [
    {
      "type": "network",
      "amount": "0.02",
      "currency": "ETH"
    }
  ]
}

Payment Processing

{
  "event": "payment.processing",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "offrampId": "offramp_test123456789",
  "timestamp": "2025-10-03T14:35:00Z",
  "subStatus": "ongoing_checks",
  "paymentProcessor": "request-tech",
  "rawPayload": {
    "status": "ongoing_checks",
    "providerId": "provider_test123"
  }
}

Payment Partial

{
  "event": "payment.partial",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "explorer": "https://scan.request.network/request/0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "amount": "50.0",
  "totalAmountPaid": "50.0",
  "expectedAmount": "100.0",
  "timestamp": "2025-10-03T14:30:00Z",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "network": "ethereum",
  "currency": "USDC",
  "paymentCurrency": "USDC",
  "isCryptoToFiat": false,
  "subStatus": "",
  "paymentProcessor": "request-network",
  "fees": []
}

Payment Failed

{
  "event": "payment.failed",
  "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
  "paymentReference": "0x2c3366941274c34c",
  "subStatus": "insufficient_funds",
  "paymentProcessor": "request-network"
}

Compliance Updated

{
  "event": "compliance.updated",
  "clientUserId": "user_test123456789",
  "kycStatus": "approved",
  "agreementStatus": "completed",
  "isCompliant": true,
  "timestamp": "2025-10-03T14:30:00Z",
  "rawPayload": {
    "verificationLevel": "full",
    "documents": "verified"
  }
}

Implementation Examples

For a complete working example, see the EasyInvoice demo which implements webhook handling for payment notifications.

Express.js
Next.js

import express from "express";
import crypto from "node:crypto";

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// Use raw body parser to capture exact request bytes for signature verification
app.use(
  express.raw({
    type: "application/json",
    verify: (req, _res, buf) => {
      req.rawBody = buf;
    },
  })
);

app.post("/webhook/payment", async (req, res) => {
  try {
    // Verify signature against raw body
    const signature = req.headers["x-request-network-signature"];
    const rawBody = req.rawBody;

    const expectedSignature = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(rawBody)
      .digest("hex");

    if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    // Parse JSON only after verifying signature
    const body = JSON.parse(rawBody.toString("utf8"));
    const isTest = req.headers["x-request-network-test"] === "true";

    if (isTest) {
      console.log("Received test webhook");
    }

    // Process webhook based on event type
    const { event, requestId } = body;
    
    switch (event) {
      case "payment.confirmed":
        await handlePaymentConfirmed(body);
        break;
      case "payment.processing":
        await handlePaymentProcessing(body);
        break;
      case "compliance.updated":
        await handleComplianceUpdate(body);
        break;
      default:
        console.log(`Unhandled event: ${event}`);
    }

    return res.status(200).json({ success: true });
    
  } catch (error) {
    console.error("Webhook processing error:", error);
    return res.status(500).json({ error: "Processing failed" });
  }
});

// app/api/webhook/route.ts
import crypto from "node:crypto";
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  try {
    // Read raw body for signature verification
    const rawBody = await request.text();
    const signature = request.headers.get("x-request-network-signature");
    const expectedSignature = crypto
      .createHmac("sha256", process.env.WEBHOOK_SECRET!)
      .update(rawBody)
      .digest("hex");

    if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
    }

    // Parse JSON after verifying signature
    const body = JSON.parse(rawBody);

    // Process webhook
    const { event, requestId } = body;
    
    // Your business logic here
    await processWebhookEvent(event, body);

    return NextResponse.json({ success: true }, { status: 200 });
    
  } catch (error) {
    console.error("Webhook error:", error);
    return NextResponse.json(
      { error: "Internal server error" }, 
      { status: 500 }
    );
  }
}

Testing

Portal Testing

Go to Platform Settings → Webhooks in Request Portal
Create a webhook if you haven’t already
Select the webhook event type and click Send test event
Monitor your endpoint logs for test requests

Test Webhook Identification

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

app.post("/webhook", (req, res) => {
  const isTest = req.headers["x-request-network-test"] === "true";
  
  if (isTest) {
    console.log("Received test webhook");
    // Handle test scenario
  }
  
  // Process normally...
});

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 Portal configuration
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

Debugging Tips

Use ngrok request inspector to see raw webhook data
Monitor retry counts in headers to identify issues
Test with Portal’s “Send test webhooks” feature

Webhooks & Events

High-level webhook concepts and workflow

EasyInvoice Demo

Complete webhook implementation example

Authentication

API key setup and webhook security

Payment Processing

Understanding payment lifecycle events

Request Portal

Configure webhooks and manage API keys

Request Scan

Explore transactions and request details

​Overview

​Webhook Configuration

​Setup in Portal

​Local Development

​Event Types

​Payment Events

​Processing Events

​Request Events

​Compliance Events

​Security Implementation

​Signature Verification

​Security Requirements

​Request Headers

​Retry Logic

​Automatic Retries

​Response Handling

​Error Logging

​Payload Examples

​Payment Confirmed

​Payment Processing

​Payment Partial

​Payment Failed

​Compliance Updated

​Implementation Examples

​Testing

​Portal Testing

​Test Webhook Identification

​Best Practices

​Error Handling

​Performance

​Troubleshooting

​Common Issues

​Debugging Tips

​Related Documentation

Webhooks & Events

EasyInvoice Demo

Authentication

Payment Processing

Request Portal

Request Scan

Overview

Webhook Configuration

Setup in Portal

Local Development

Event Types

Payment Events

Processing Events

Request Events

Compliance Events

Security Implementation

Signature Verification

Security Requirements

Request Headers

Retry Logic

Automatic Retries

Response Handling

Error Logging

Payload Examples

Payment Confirmed

Payment Processing

Payment Partial

Payment Failed

Compliance Updated

Implementation Examples

Testing

Portal Testing

Test Webhook Identification

Best Practices

Error Handling

Performance

Troubleshooting

Common Issues

Debugging Tips

Related Documentation