The API, documented like the floor.

HTTP/1.1 401 Unauthorized
{ "error": { "code": "unauthorized", "message": "Unknown API key." } }

HTTP/1.1 403 Forbidden
{ "error": { "code": "forbidden", "message": "This API key is revoked or expired." } }

HTTP/1.1 503 Service Unavailable
{ "error": { "code": "api_unavailable", "message": "API access is not yet enabled." } }

POST /your/webhook/path HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: VIG-Webhooks/1.0
X-VIG-Event: order.invoice_issued
X-VIG-Delivery: 0f6a2c9e-4d17-4b52-8e33-b1a9c5d2e7f4
X-VIG-Signature: t=1783717504,v1=5c9c17b3e4f2...a94d

{
  "event": "order.invoice_issued",
  "occurred_at": "2026-07-09T21:05:04.118Z",
  "data": {
    "order_type": "auction",
    "lot_id": "VIG-AUC-2026-0341",
    "title": "Dell Latitude 5440 - 24-unit lot",
    "hammer_price": "2850.00",
    "premium_pct": 15,
    "premium_amount": "427.50",
    "total": "3277.50",
    "status": "issued"
  }
}

{
  "event": "custody.status_changed",
  "occurred_at": "2026-07-15T19:22:05.244Z",
  "data": {
    "pickup_id": "6d2a9c40-91b7-4f83-a1c2-5e8f0b3d7a19",
    "reference_code": "VIG-2026-0712-9A3B",
    "status": "scheduled",
    "changed_at": "2026-07-15T19:22:05.112Z"
  }
}

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const WINDOW_SECONDS = 300; // reject signatures older/newer than 5 minutes

function verifyVigSignature(header, deliveryId, rawBody, secret) {
  // Parse "t=...,v1=...[,v0=...]" into { t: [...], v1: [...], v0: [...] }.
  const parts = {};
  for (const piece of header.split(',')) {
    const i = piece.indexOf('=');
    if (i <= 0) return false;
    const key = piece.slice(0, i).trim();
    (parts[key] ??= []).push(piece.slice(i + 1).trim());
  }

  const t = Number(parts.t?.[0]);
  if (!Number.isInteger(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > WINDOW_SECONDS) return false;

  // Signed message: "{delivery_id}.{timestamp}.{raw_body}".
  // v1 = current secret; v0 appears only during the 24 h rotation grace.
  const expected = createHmac('sha256', secret)
    .update(`${deliveryId}.${t}.${rawBody}`)
    .digest();
  return [...(parts.v1 ?? []), ...(parts.v0 ?? [])].some((sig) => {
    const candidate = Buffer.from(sig, 'hex');
    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
  });
}

const app = express();

// Keep the RAW body: the signature covers the exact bytes we sent.
app.post('/webhooks/vig', express.raw({ type: 'application/json' }), (req, res) => {
  const deliveryId = req.get('X-VIG-Delivery') ?? '';
  const ok = verifyVigSignature(
    req.get('X-VIG-Signature') ?? '',
    deliveryId,
    req.body.toString('utf8'),
    process.env.VIG_WEBHOOK_SECRET,
  );
  if (!ok) return res.status(400).end();

  res.status(200).end(); // ack fast (well under 10 s) - do real work async

  // Delivery is AT-LEAST-ONCE: dedupe on deliveryId before processing.
  const payload = JSON.parse(req.body.toString('utf8'));
  handleEvent(deliveryId, payload);
});

import hashlib
import hmac
import time

WINDOW_SECONDS = 300  # reject signatures older/newer than 5 minutes

def verify_vig_signature(header: str, delivery_id: str, raw_body: bytes, secret: str) -> bool:
    parts: dict[str, list[str]] = {}
    for piece in header.split(","):
        key, sep, value = piece.partition("=")
        if not sep:
            return False
        parts.setdefault(key.strip(), []).append(value.strip())

    try:
        t = int(parts["t"][0])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > WINDOW_SECONDS:
        return False

    # Signed message: "{delivery_id}.{timestamp}.{raw_body}".
    message = f"{delivery_id}.{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

    # v1 = current secret; v0 appears only during the 24 h rotation grace.
    candidates = parts.get("v1", []) + parts.get("v0", [])
    return any(hmac.compare_digest(sig, expected) for sig in candidates)