Webhooks

Real-time event notifications and webhook configuration guide

Webhook Overview

Webhooks provide real-time notifications when events occur in your Request Network integration. Instead of polling for updates, webhooks push event data to your application immediately when payments are detected, requests are created, or other significant events happen.

Webhook Events

Payment Events

payment_detected

When: Payment transaction is detected on blockchain

Use Cases:

• Show “Payment Pending” status to users
• Start order preparation
• Send confirmation emails

Typical Timing: Within 1-5 seconds of transaction

payment_confirmed

When: Payment is confirmed on blockchain (sufficient confirmations)

Use Cases:

• Complete order fulfillment
• Update accounting systems
• Release digital goods

Typical Timing: 1-15 minutes after payment

payment_failed

When: Payment transaction fails or is reverted

Use Cases:

• Notify customer of payment failure
• Reset order status
• Trigger retry workflows

Triggers: Failed transactions, insufficient gas, reverted smart contract calls

payment_partially_completed

When: Partial payment is received for a request

Use Cases:

• Update outstanding balance
• Notify of partial payment
• Allow additional payments

Common Scenarios: Installment payments, partial order fulfillment

Request Events

request_created

When: New payment request is created

Payload Includes:

• Request ID and details
• Payment information
• Custom metadata

Use Cases: CRM integration, analytics tracking

request_updated

When: Request metadata or status is modified

Payload Includes:

• Updated fields
• Previous values
• Change timestamp

Use Cases: Audit trails, status synchronization

Subscription Events

subscription_renewed

When: Recurring payment is successfully processed

Use Cases:

• Extend subscription period
• Send renewal confirmation
• Update billing systems

For: Subscription use cases

subscription_failed

When: Recurring payment fails

Use Cases:

• Notify customer of failed payment
• Initiate payment retry
• Manage subscription status

Common Causes: Insufficient funds, expired payment methods

Webhook Configuration

Setting Up Webhooks

1. Configure Endpoint

   Set up a webhook endpoint URL in the Request Portal

2. Select Events

   Choose which event types you want to receive

3. Test Endpoint

   Use the test webhook feature to verify your endpoint

4. Go Live

   Enable webhooks for production traffic

Webhook Endpoint Requirements

HTTP Requirements

Endpoint Specifications:

• Must be publicly accessible HTTPS URL
• Should return 2xx status code for successful processing
• Timeout limit: 30 seconds
• Must handle duplicate events (idempotency)

app.post('/webhooks/request-network', (req, res) => {
  try {
    // Process webhook event
    const { eventType, data } = req.body;
    
    // Your business logic here
    processEvent(eventType, data);
    
    // Return success status
    res.status(200).send('OK');
    
  } catch (error) {
    // Return error status for retry
    console.error('Webhook processing error:', error);
    res.status(500).send('Error processing webhook');
  }
});

Webhook Payloads

Payment Confirmed Event

Payment Confirmed

{
  "eventType": "payment_confirmed",
  "timestamp": "2025-09-12T10:30:00Z",
  "data": {
    "requestId": "req_1234567890abcdef",
    "paymentReference": "pay_abcdef1234567890",
    "transactionHash": "0x742d35cc6cf8a8cbeff61cf82c6b8b3b42a67f1d6c1e8a7b9e2f8d5c3a1b0e9f",
    "blockNumber": 18523456,
    "networkName": "matic",
    "amount": "1000000000000000000000", // 1000 USDC (18 decimals)
    "currency": "USDC-matic",
    "payerAddress": "0x1234567890123456789012345678901234567890",
    "payeeAddress": "0x0987654321098765432109876543210987654321",
    "fees": {
      "platformFee": "25000000000000000000", // 25 USDC
      "gasFee": "0.02"
    },
    "metadata": {
      "reason": "Invoice #INV-001",
      "invoiceNumber": "INV-001",
      "customerEmail": "[e-mail]",
      "orderId": "ORD-2025-001"
    }
  }
}

Integration Examples

E-commerce Order Processing

Express.js Handler

app.post('/webhooks/payment-confirmed', async (req, res) => {
  try {
    // Verify webhook signature
    if (!verifyWebhookSignature(req)) {
      return res.status(401).send('Unauthorized');
    }
    
    const { eventType, data } = req.body;
    
    if (eventType === 'payment_confirmed') {
      const orderId = data.metadata.orderId;
      
      // Update order status
      await updateOrder(orderId, {
        status: 'paid',
        paymentHash: data.transactionHash,
        paidAt: data.timestamp,
        paymentMethod: 'crypto'
      });
      
      // Send confirmation email
      await sendOrderConfirmation(orderId);
      
      // Trigger fulfillment
      await triggerOrderFulfillment(orderId);
      
      console.log(`Order ${orderId} marked as paid`);
    }
    
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('Error processing webhook');
  }
});

Database Integration

Payment Tracking

-- Create table for payment tracking
CREATE TABLE payment_events (
  id SERIAL PRIMARY KEY,
  request_id VARCHAR(255) NOT NULL,
  event_type VARCHAR(50) NOT NULL,
  transaction_hash VARCHAR(66),
  block_number INTEGER,
  amount DECIMAL(36, 18),
  currency VARCHAR(20),
  payer_address VARCHAR(42),
  payee_address VARCHAR(42),
  metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  processed_at TIMESTAMP,
  INDEX idx_request_id (request_id),
  INDEX idx_event_type (event_type),
  INDEX idx_created_at (created_at)
);

Testing Webhooks

Webhook Testing Tools

ngrok

Local Development:

• Expose local server to internet
• Test webhooks during development
• Secure tunnels with authentication

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use ngrok URL as webhook endpoint
# https://abc123.ngrok.io/webhooks/request-network

Webhook.site

Quick Testing:

• Temporary webhook endpoints
• Inspect webhook payloads
• No setup required

Process:

1. Go to webhook.site
2. Copy the unique URL
3. Use as webhook endpoint
4. View received webhooks in browser

Test Event Simulation

Test Webhooks in Request Portal

Use the Request Portal to send test webhook events to your endpoint for development and testing.

What’s Next?

🔐 Authentication

Secure your API and webhook endpoints

⚙️ Advanced Features

Learn more about webhook event types and handling

🛠️ Integration Patterns

Common webhook integration patterns and best practices