Webhooks

Wellth-Signature: t=1793607300,v1=feae610c47b9d3b49bd80f86f1f6977a0cead158e0b1f1981d4a771fca2950c8

const crypto = require("node:crypto");

// rawBody: the request body exactly as received (a Buffer or string), before any JSON parsing.
// header: the Wellth-Signature header. secret: your whsec_... signing secret.
function verifyWellthSignature(rawBody, header, secret, nowSec = Math.floor(Date.now() / 1000)) {
  const parts = {};
  for (const item of String(header || "").split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(nowSec - t) > 300) return false; // more than 5 minutes off: refuse

  const expected = crypto.createHmac("sha256", secret).update(t + ".").update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const express = require("express");
const app = express();

// express.raw keeps the body as bytes: the signature is over the raw body, not re-serialised JSON.
app.post("/wellth/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verifyWellthSignature(req.body, req.get("Wellth-Signature"), process.env.WELLTH_WEBHOOK_SECRET)) {
    return res.status(401).send("Bad signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  if (process.env.NODE_ENV === "production" && !event.livemode) return res.sendStatus(200); // a test event

  // Act once per event id (store it; a repeat is answered 200 and ignored).
  await handleWellthEvent(event);
  res.sendStatus(200);
});

// app/api/wellth/webhook/route.ts
export async function POST(req: Request) {
  const raw = await req.text(); // the raw body, before JSON.parse
  if (!verifyWellthSignature(raw, req.headers.get("wellth-signature"), process.env.WELLTH_WEBHOOK_SECRET!)) {
    return new Response("Bad signature", { status: 401 });
  }
  const event = JSON.parse(raw);
  if (process.env.NODE_ENV === "production" && !event.livemode) return new Response(null, { status: 200 });
  await handleWellthEvent(event); // idempotent on event.id
  return new Response(null, { status: 200 });
}

<?php
// $rawBody: file_get_contents('php://input'), before json_decode.
function wellth_verify_signature(string $rawBody, string $header, string $secret, ?int $now = null): bool
{
    $parts = [];
    foreach (explode(',', $header) as $item) {
        $kv = explode('=', trim($item), 2);
        if (count($kv) === 2) {
            $parts[$kv[0]] = $kv[1];
        }
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) {
        return false;
    }
    $t = (int) $parts['t'];
    if (abs(($now ?? time()) - $t) > 300) {
        return false; // more than 5 minutes off: refuse
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_WELLTH_SIGNATURE'] ?? '';
if (!wellth_verify_signature($raw, $header, getenv('WELLTH_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit('Bad signature');
}
$event = json_decode($raw, true);
// Act once per $event['id'], then answer 200.
http_response_code(200);

import hashlib
import hmac
import time


def verify_wellth_signature(raw_body: bytes, header: str, secret: str, now=None) -> bool:
    """raw_body: the request body as bytes, before json.loads (Flask: request.get_data())."""
    parts = {}
    for item in (header or "").split(","):
        key, sep, value = item.strip().partition("=")
        if sep:
            parts[key] = value
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1:
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(t)) > 300:
        return False  # more than 5 minutes off: refuse
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


# Flask
# @app.post("/wellth/webhook")
# def wellth_webhook():
#     if not verify_wellth_signature(request.get_data(), request.headers.get("Wellth-Signature", ""), os.environ["WELLTH_WEBHOOK_SECRET"]):
#         return "Bad signature", 401
#     event = request.get_json()
#     # Act once per event["id"], then answer 200.
#     return "", 200

whsec_EXAMPLEonlyEXAMPLEonlyEXAMPLE000

{"id":"evt_3f9a1c7e5b2d8f4a6c0e9b1d","type":"learner.payment_succeeded","livemode":false,"created":"2026-11-02T08:15:00.000Z","data":{"externalRef":"oca_stu_ckx123","payNumber":"2047118530","wellthRef":"WP-8F3K2Q7A","amountMinor":"150000","currency":"UGX","paidAt":"2026-11-02T08:14:51.000Z","method":"MOBILE_MONEY","payer":"J. N.","termLabel":"Term 3, 2026"}}

t=1793607300,v1=feae610c47b9d3b49bd80f86f1f6977a0cead158e0b1f1981d4a771fca2950c8

// send-test-event.js: node send-test-event.js http://localhost:4000/wellth/webhook
const crypto = require("node:crypto");

function signWellthPayload(body, secret, nowSec = Math.floor(Date.now() / 1000)) {
  const v1 = crypto.createHmac("sha256", secret).update(nowSec + "." + body).digest("hex");
  return "t=" + nowSec + ",v1=" + v1;
}

const body = JSON.stringify({
  id: "evt_" + crypto.randomBytes(12).toString("hex"),
  type: "learner.payment_succeeded",
  livemode: false,
  created: new Date().toISOString(),
  data: {
    externalRef: "oca_stu_ckx123", payNumber: "2047118530", wellthRef: "WP-8F3K2Q7A",
    amountMinor: "150000", currency: "UGX", paidAt: new Date().toISOString(),
    method: "MOBILE_MONEY", payer: "J. N.", termLabel: "Term 3, 2026",
  },
});

const secret = process.env.WELLTH_WEBHOOK_SECRET; // the same whsec_... your receiver checks with
fetch(process.argv[2], {
  method: "POST",
  headers: { "Content-Type": "application/json", "Wellth-Signature": signWellthPayload(body, secret) },
  body,
}).then((r) => console.log("Your receiver answered", r.status));