Signature Verification
Verify the exact BramaPay webhook v2 envelope in Node.js.
The request includes X-Webhook-Version, X-Event-Id, X-Delivery-Id, X-Event-Type, X-Key-Id, X-Timestamp, X-Attempt, X-Idempotency-Key, and X-Signature-SHA256.
The exact UTF-8 signing input is JSON.stringify of this ordered array. Version is the number 2; every other header value is a string:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyBramaPayWebhook(
rawBody: Buffer,
headers: Record<string, string | undefined>,
secret: string,
) {
const required = (name: string) => {
const value = headers[name.toLowerCase()];
if (!value) throw new Error(`Missing ${name}`);
return value;
};
const version = required("x-webhook-version");
const eventId = required("x-event-id");
const deliveryId = required("x-delivery-id");
const eventType = required("x-event-type");
const timestamp = required("x-timestamp");
const keyId = required("x-key-id");
const attempt = required("x-attempt");
const signature = required("x-signature-sha256");
if (version !== "2" || required("x-idempotency-key") !== eventId)
throw new Error("Invalid webhook envelope");
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300)
throw new Error("Stale webhook");
const input = JSON.stringify([
"vaultless.webhook",
2,
eventId,
deliveryId,
eventType,
timestamp,
keyId,
attempt,
rawBody.toString("utf8"),
]);
const expected = Buffer.from(createHmac("sha256", secret).update(input).digest("hex"), "hex");
const actual = Buffer.from(signature, "hex");
if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
throw new Error("Invalid webhook signature");
return { eventId, eventType, keyId };
}The protocol namespace remains vaultless.webhook for compatibility. Capture the raw body before JSON parsing and enforce a 256 KiB request limit.