Webhook Security - BillStack

Because your webhook URL is public, anyone could try to POST fake events to it. BillStack signs every webhook with your secret key so you can confirm a request really came from us and was not altered in transit. Verify the signature before you trust an event. Each webhook arrives with these headers:

Header	Description
`x-wiaxy-signature-256`	The signature to verify. HMAC-SHA256 (hex) of `"{timestamp}.{rawBody}"`, keyed with your secret key.
`x-wiaxy-timestamp`	The Unix timestamp (seconds) used in the signed string.
`x-wiaxy-signature`	Legacy. A static `md5(secret_key)`, kept for backward compatibility only.

The new signature (recommended)

Verify x-wiaxy-signature-256. It is computed over the exact body of each request, so it proves both authenticity (only someone with your secret key could produce it) and integrity (any change to the body invalidates it). To verify:

Read x-wiaxy-timestamp and the raw, unparsed request body.
Build the string "{timestamp}.{rawBody}".
Compute HMAC-SHA256 of that string with your secret key, as hex.
Compare it to x-wiaxy-signature-256 using a constant-time comparison.
Reject the request if the timestamp is older than a few minutes, to stop replays.

import crypto from "crypto";

function verifyWebhook(rawBody, headers, secretKey) {
  const timestamp = headers["x-wiaxy-timestamp"];
  const signature = headers["x-wiaxy-signature-256"];

  // Reject stale events (replay protection).
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

function verify_webhook($rawBody, $headers, $secretKey) {
    $timestamp = $headers['x-wiaxy-timestamp'] ?? '';
    $signature = $headers['x-wiaxy-signature-256'] ?? '';

    // Reject stale events (replay protection).
    if (abs(time() - (int)$timestamp) > 300) return false;

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secretKey);

    return hash_equals($expected, $signature);
}

Always verify against the raw, unparsed request body : exactly the bytes you received. Re-serialising the JSON (for example JSON.stringify(req.body)) can reorder keys or change whitespace, producing a different signature and a failed check.

The legacy signature

Older integrations may still check x-wiaxy-signature, a static md5(secret_key). Because it never changes between requests, it does not prove the body is intact and is weaker than the HMAC signature. It is still sent for backward compatibility, but new integrations should verify x-wiaxy-signature-256 instead.

Both headers are sent on every webhook, so you can migrate from the legacy signature to the new one without any change on our side : just start verifying x-wiaxy-signature-256.