Signature Verification

Vixzz signs every webhook callback with HMAC-SHA256 using your private Webhook Secret. Validate the signature over the original bytes before parsing. Reject timestamps more than five minutes in the past or future. A valid signature does not prevent replay within that window.

In one database transaction, insert the event ID into a table with a unique constraint and apply the business update. A duplicate ID must not repeat payouts or credits. Commit before returning 2xx; a failed transaction must remain retryable. Keep the webhook secret only on your server, never in a browser bundle.

Request Headers

HeaderTypeStatusDescription
X-Vixzz-SignaturestringRequiredt=<unix-seconds>,v1=<64 hex characters>
Content-TypestringRequiredapplication/json
HEADERX-Vixzz-Signature: t=1757212200,v1=9f82...Live & Sandbox

Request Code Snippets (cURL, Node, Python, PHP, Go)

JSON Return Response Body (200 OK)

Node.js Verification Function
import { createHmac, timingSafeEqual } from 'node:crypto';

// Pass the original request bytes before any JSON parsing.
export function verifyVixzzWebhook(rawBody, signatureHeader, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  if (!Buffer.isBuffer(rawBody) || rawBody.length > 1024 * 1024 ||
      typeof signatureHeader !== 'string' || typeof secret !== 'string' || !secret ||
      !Number.isSafeInteger(nowSeconds)) return false;
  const parts = /^t=([0-9]{1,12}),v1=([0-9a-fA-F]{64})$/.exec(signatureHeader);
  if (!parts) return false;
  const timestamp = Number(parts[1]);
  if (!Number.isSafeInteger(timestamp) || Math.abs(nowSeconds - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(parts[1] + '.')
    .update(rawBody)
    .digest();
  return timingSafeEqual(Buffer.from(parts[2], 'hex'), expected);
}