Webhook reconciliation

What you’ll build

A webhook handler that receives signed payment events from Request Network, verifies the signature, and triggers your downstream systems — order fulfillment, invoice closeout, accounting entries, customer email. Polling-free, idempotent, retry-safe. Audience: any backend integrating Request Network where payment events drive state changes downstream.

The 12 events

Category	Event	When it fires
Payment (core)	`payment.confirmed`	Payment fully settled on-chain
	`payment.partial`	Partial payment received, more expected
	`payment.failed`	Payment execution failed (recurring, cross-chain)
	`payment.refunded`	Payment refunded to payer
Payment (Client ID)	`payment.confirmed.client_id`	Same as `payment.confirmed`, request was created via Client ID — payload includes `clientId` and `origin`
	`payment.partial.client_id`	Client ID-scoped partial
Payment (Checkout)	`payment.confirmed.checkout`	Same as `payment.confirmed`, request originated from a Secure Payment link
	`payment.partial.checkout`	Secure Payment-scoped partial
Processing	`payment.processing`	Crypto-to-fiat offramp in progress (with detailed `subStatus`)
Request	`request.recurring`	A new recurring billing cycle fired
Compliance	`compliance.updated`	KYC or agreement status changed
Bank details	`payment_detail.updated`	Bank account verification status changed

For the full payload schemas, see the Webhooks reference.

Setup

Get a Client ID

Complete steps 1–3 of the Quickstart. Note your clientId.

POST https://auth.request.network/v1/webhook with header x-client-id: <yours> and body { "url": "https://yourapp.com/webhooks/request-network" }.Save the returned secret immediately — it’s only shown once.

Test delivery

Fire a test event from the auth API docs with body { "eventType": "payment.confirmed" }. The request will arrive with header x-request-network-test: true.

Handler — reference implementation

A signature-verifying Express handler with idempotency. Hardened for production: verifies against the raw body, uses constant-time comparison, deduplicates on x-request-network-delivery.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
import { Redis } from "ioredis";

const app = express();
const redis = new Redis(process.env.REDIS_URL!);
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;

app.post(
  "/webhooks/request-network",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-request-network-signature"] as string;
    const deliveryId = req.headers["x-request-network-delivery"] as string;
    const isTest = req.headers["x-request-network-test"] === "true";

    if (!signature || !deliveryId) {
      return res.status(400).send("missing headers");
    }

    // 1. Verify signature against the RAW body — never re-stringify
    const expected = createHmac("sha256", WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    const sigBuf = Buffer.from(signature, "hex");
    const expBuf = Buffer.from(expected, "hex");

    if (
      sigBuf.length !== expBuf.length ||
      !timingSafeEqual(sigBuf, expBuf)
    ) {
      return res.status(401).send("invalid signature");
    }

    // 2. Idempotency: dedupe on delivery ID
    const claim = await redis.set(
      `webhook:${deliveryId}`,
      "1",
      "EX",
      86400, // 24h
      "NX",
    );
    if (!claim && !isTest) {
      return res.status(200).send("duplicate, ignored");
    }

    // 3. Parse and route
    const event = JSON.parse(req.body.toString("utf8"));

    try {
      await handleEvent(event);
    } catch (err) {
      // Return non-2xx to trigger retry (1s, 5s, 15s — up to 3 retries)
      console.error("handler failed", err);
      return res.status(500).send("handler error");
    }

    res.status(200).send("ok");
  },
);

async function handleEvent(event: any) {
  switch (event.event) {
    case "payment.confirmed":
    case "payment.confirmed.client_id":
    case "payment.confirmed.checkout":
      await markOrderPaid(event.requestId, event.txHash);
      break;

    case "payment.partial":
    case "payment.partial.client_id":
    case "payment.partial.checkout":
      await recordPartialPayment(
        event.requestId,
        event.amount,
        event.totalAmountPaid,
      );
      break;

    case "payment.failed":
      await flagFailedPayment(event.requestId);
      break;

    case "request.recurring":
      await onRecurringInvoice(event.originalRequestId, event.requestId);
      break;

    case "compliance.updated":
      await syncKycStatus(event.clientUserId, event.kycStatus);
      break;

    // ... others
  }
}

Headers reference

Header	Description
`x-request-network-signature`	HMAC-SHA256 of the raw JSON body, hex-encoded
`x-request-network-delivery`	ULID — use as idempotency key
`x-request-network-retry-count`	`0`–`3`, current retry attempt
`x-request-network-test`	`true` only for `/v1/webhook/test` deliveries

Retry policy

Attempt	Delay	Cumulative time
0 (initial)	—	t=0
1	1s	t+1s
2	5s	t+6s
3	15s	t+21s

After 4 total attempts (initial + 3 retries) the delivery is dropped. Triggers: any non-2xx response, timeout, connection error. Default request timeout is 5s.

Common patterns

Idempotency

The same payment.confirmed event might arrive twice (network blip, retry overlap). Dedupe on x-request-network-delivery.

Routing by Client ID

If your platform has many merchants, give each their own Client ID. The webhook payload includes clientId so you can route events to the right tenant.

async function markOrderPaid(requestId: string, txHash: string) {
  const order = await db.orders.findOne({ where: { requestId } });
  if (!order) return; // not ours
  await db.orders.update({ where: { id: order.id }, data: { paidAt: new Date(), txHash } });
}

Slack alerts on failure

case "payment.failed":
  await fetch(SLACK_WEBHOOK, {
    method: "POST",
    body: JSON.stringify({
      text: `:warning: Payment failed for request ${event.requestId}`,
    }),
  });
  break;

Crypto-to-fiat status tracking

The payment.processing event includes a subStatus field that progresses through initiated → pending_internal_assessment → ongoing_checks → sending_fiat → fiat_sent. Surface this in your UI so the payee sees real-time offramp progress.

Local development

Use ngrok to expose localhost during development:

ngrok http 3000
# Pass the https://xxxxx.ngrok-free.app URL to POST /v1/webhook (above)

Local URLs (localhost, 127.0.0.1) are accepted by the auth API for testing. HTTPS is required in production.

Webhooks reference

Full payload schemas for every event type.

Webhooks & Events

High-level concepts and event categories.

🚀 Get Started

🎯 Use Cases

What you’ll build

The 12 events

Setup

Handler — reference implementation

Headers reference

Retry policy

Common patterns

Idempotency

Routing by Client ID

Slack alerts on failure

Crypto-to-fiat status tracking

Local development

Webhooks reference

Webhooks & Events

🚀 Get Started

🎯 Use Cases

Documentation Index

​What you’ll build

​The 12 events

​Setup

​Handler — reference implementation

​Headers reference

​Retry policy

​Common patterns

​Idempotency

​Routing by Client ID

​Slack alerts on failure

​Crypto-to-fiat status tracking

​Local development

​Related

Webhooks reference

Webhooks & Events

What you’ll build

The 12 events

Setup

Handler — reference implementation

Headers reference

Retry policy

Common patterns

Idempotency

Routing by Client ID

Slack alerts on failure

Crypto-to-fiat status tracking

Local development

Related