Enterprise Integration Docs

Headers sent on every delivery (v1)

• X-Pinbar-Signature: t=<unix>,n=<nonce>,v1=<hex> — HMAC-SHA256 of `$${t}.$${n}.$${body}` using your webhook secret
• X-Pinbar-Timestamp — Unix seconds at the time of signing
• X-Pinbar-Nonce — Per-delivery random UUID for replay protection
• X-Pinbar-Event — Event type (e.g. trade.ingested)
• X-Pinbar-Delivery — Stable delivery UUID for idempotency
• X-Pinbar-Signature-Version: v1

Verify the signature (Node.js)

import crypto from "crypto";

const TOLERANCE_SECONDS = 300; // reject deliveries older than 5 minutes
const seenNonces = new Set();  // back this with Redis in production

export function verifyPinbarWebhook(rawBody, headers, secret) {
  const sig = headers["x-pinbar-signature"] || "";
  const parts = Object.fromEntries(sig.split(",").map(p => p.split("=")));
  const t = Number(parts.t), n = parts.n, provided = parts.v1;
  if (!t || !n || !provided) throw new Error("malformed signature");

  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) {
    throw new Error("timestamp out of tolerance");
  }
  if (seenNonces.has(n)) throw new Error("replay detected");
  seenNonces.add(n);

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

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
    throw new Error("signature mismatch");
  }
}