Integration security

Keys are formatted ak_live_<32 base32 chars> for production, or ak_test_… for the sandbox. We persist a SHA-256 hash plus the first 8 + last 4 characters — the full secret is shown once at mint time and is unrecoverable afterwards.

# Environment variable setup (recommended)
export ADAPT_API_KEY="ak_live_..."

# Don't do this — keys in source ship to every reader of the repo
const apiKey = "ak_live_..."

Every webhook delivery carries a X-AdaptLive-Signature header in this shape:

X-AdaptLive-Signature: t=1717009200,v1=8a3e…<64 hex chars>

• t — the unix-second timestamp at the moment we signed.
• v1 — HMAC-SHA256(${t}.${rawBody}) using the subscription's whsec_… signing secret, hex encoded.

Reconstruct the same payload (`${t}.${rawBody}`) on your side, recompute the HMAC, and compare with crypto.timingSafeEqual(or your language's constant-time equivalent).

Replay protection. Reject anything where |now - t| > 300s.

// Node.js — copy/paste verifier
import crypto from "node:crypto";

export function verifyAdaptLiveWebhook(args: {
  signingSecret: string; // 'whsec_...' from POST /v1/webhooks
  rawBody: string;       // the exact bytes you received (don't re-stringify)
  signatureHeader: string; // value of 'X-AdaptLive-Signature'
  toleranceSeconds?: number;
}): { ok: true } | { ok: false; reason: string } {
  const parts = args.signatureHeader.split(",").map((s) => s.trim());
  const tEntry = parts.find((p) => p.startsWith("t="));
  const v1Entry = parts.find((p) => p.startsWith("v1="));
  if (!tEntry || !v1Entry) return { ok: false, reason: "Malformed header" };

  const t = Number(tEntry.slice(2));
  const v1 = v1Entry.slice(3);
  const now = Math.floor(Date.now() / 1000);
  const tolerance = args.toleranceSeconds ?? 300;
  if (!Number.isFinite(t) || Math.abs(now - t) > tolerance) {
    return { ok: false, reason: "Timestamp outside tolerance window" };
  }

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

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  const ok = a.length === b.length && crypto.timingSafeEqual(a, b);
  return ok ? { ok: true } : { ok: false, reason: "Signature mismatch" };
}

Python, Ruby, and Go verifier snippets live on the Webhooks reference page.