Webhooks

POST /webhooks/radok HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Radok-Event-Id: evt_7c1f3a9d2b8e4506
X-Radok-Signature: t=1755948123,v1=5f2c...e91a

{
  "id": "evt_7c1f3a9d2b8e4506",
  "type": "collection.success",
  "createdAt": "2026-08-23T11:42:10.000Z",
  "data": {
    "reference": "col_3a7d5e1f9b2c4d68",
    "amount": { "value": 500000, "currency": "NGN" },
    "netAmount": { "value": 495000, "currency": "NGN" },
    "paidAt": "2026-08-23T11:42:10.000Z"
  }
}

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

const app = express();
const SECRET = process.env.RADOK_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60;

function verify(rawBody, header) {
  if (!header) return false;

  // "t=1755948123,v1=5f2c...,v1_prev=8a3d..."
  const parts = Object.fromEntries(
    header.split(",").map((pair) => pair.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;

  // Reject stale deliveries so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  // Accept EITHER signature: during a rotation window Radok signs with both the
  // new secret (v1) and the previous one (v1_prev).
  return ["v1", "v1_prev"].some((field) => {
    const candidate = parts[field];
    if (!candidate || candidate.length !== expected.length) return false;
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(candidate));
  });
}

// express.raw, NOT express.json — the signature covers the exact bytes we sent,
// and JSON.parse followed by JSON.stringify does not reproduce them.
app.post(
  "/webhooks/radok",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body.toString("utf8");

    if (!verify(rawBody, req.get("X-Radok-Signature"))) {
      return res.status(400).send("invalid signature");
    }

    const event = JSON.parse(rawBody);

    // Acknowledge first, work afterwards. Radok gives you 15 seconds.
    res.status(200).send("ok");
    await handleEvent(event);
  },
);

import hashlib, hmac, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["RADOK_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 5 * 60


def verify(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False

    parts = dict(pair.split("=", 1) for pair in header.split(","))
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False

    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        SECRET, f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()

    # Either signature is acceptable during a rotation window.
    return any(
        hmac.compare_digest(expected, parts[field])
        for field in ("v1", "v1_prev")
        if field in parts
    )


@app.post("/webhooks/radok")
def radok_webhook():
    # get_data() gives the exact bytes; request.json would not round-trip.
    raw_body = request.get_data()

    if not verify(raw_body, request.headers.get("X-Radok-Signature")):
        return "invalid signature", 400

    event = request.get_json()
    enqueue_event(event)   # do the work off the request thread
    return "ok", 200

async function handleEvent(event) {
  // Insert-if-absent on the event id. A duplicate delivery loses the race and
  // returns here without doing the work twice.
  const inserted = await db.processedEvents.insertIfAbsent(event.id);
  if (!inserted) return;

  switch (event.type) {
    case "collection.success":
      await markOrderPaid(event.data.reference, event.data.netAmount);
      break;
    case "collection.failed":
      await releaseOrder(event.data.reference, event.data.reason);
      break;
    case "payout.success":
      await markPayoutSettled(event.data.reference);
      break;
    case "payout.failed":
      await markPayoutFailed(event.data.reference, event.data.reason);
      break;
    default:
      // Unknown types are normal — we add events over time. Ignore, don't throw.
      break;
  }
}