Verify VTPE Webhook Signatures with HMAC-SHA256

Learn how to verify VTPE webhook X-Signature headers using HMAC-SHA256 over the raw payload concatenated with the X-Timestamp value.

Mizaniya Pay VTPE sends webhooks with an X-Signature header so you can verify that each event truly came from VTPE. This page explains how the signature is computed and how to validate it in your server code.

How the Signature Is Computed

VTPE signs every webhook using HMAC-SHA256 with your HMAC Secret. The message input is the raw request body concatenated directly with the X-Timestamp header value (no delimiter or separator). The resulting digest is plain hex and placed in the X-Signature header with no prefix.

Signature = HMAC-SHA256(rawBody + timestamp, HMAC_SECRET)
Header:    X-Signature: <hex digest>

For example, if the raw body is {"event":"payment.success","data":{"reference":"ORD-123"}} and X-Timestamp is 1718000000, the signed message is exactly:

{"event":"payment.success","data":{"reference":"ORD-123"}}1718000000

Verification Steps

Use raw request bytes (before any JSON parsing) when computing the signature. Polling or re-serializing the payload will change whitespace and break verification.

1. Read the raw body before JSON parsing

   Capture the exact bytes VTPE sent. In Express, use express.raw(). In Flask, use request.get_data().

2. Read the X-Timestamp header

   Capture the exact X-Timestamp string value from the incoming request headers.

3. Read the X-Signature header

   Capture the exact X-Signature hex string sent by VTPE.

4. Compute the expected signature

   Calculate HMAC-SHA256(rawBody + timestamp, HMAC_SECRET) and encode the result as a lowercase hex string.

5. Compare signatures in constant time

   Use a timing-safe comparison function (for example, crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python).

6. Return HTTP 200 on success, 400 on failure

   If the signatures match, parse the body and respond with 200 and {"success": true}. If they do not match, respond with 400.

Code Examples

Node.js

import crypto from "crypto";
import express from "express";

const app = express();

// Use raw body middleware BEFORE JSON parsing
app.use("/webhooks/vtpe", express.raw({ type: "application/json" }));

app.post("/webhooks/vtpe", (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.headers["x-timestamp"] ?? "";
  const receivedSig = req.headers["x-signature"] ?? "";

  const expectedSig = crypto
    .createHmac("sha256", process.env.VTPE_HMAC_SECRET)
    .update(rawBody + timestamp)
    .digest("hex");

  const valid = crypto.timingSafeEqual(
    Buffer.from(expectedSig, "utf8"),
    Buffer.from(receivedSig, "utf8")
  );

  if (!valid) {
    return res.status(400).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(rawBody);
  // handle event...
  return res.status(200).json({ success: true });
});

Always read the raw body before JSON parsing or body re-serialization. Re-encoding a parsed object may change field order or whitespace and cause the computed signature to differ from X-Signature, even for otherwise valid requests.

After verifying the signature, also validate that X-Timestamp is within plus or minus five minutes of your server’s current time. Rejecting old timestamps prevents replay attacks where an attacker resends a captured webhook request.