API: webhooks

# Standard bq_live_... key carrying the admin (or gamify:admin) scope.
curl -X POST https://api.bricqs.co/api/v1/gamify/webhooks \
  -H "X-API-Key: bq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-progression-sink",
    "url": "https://api.your-app.com/bricqs/webhooks",
    "events": [
      "badge.earned.v1",
      "tier.changed.v1",
      "points.awarded.v1",
      "reward.claimed.v1",
      "referral.converted.v1"
    ],
    "retry_count": 3,
    "timeout_seconds": 10
  }'

import crypto from "crypto";

const TOLERANCE_SECONDS = 300;

export async function POST(req: Request) {
  const raw = await req.text();
  const header = req.headers.get("x-bricqs-signature") ?? "";

  // Header format: t={timestamp},v1={hex_signature}
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=", 2) as [string, string])
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1 ?? "";

  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) {
    return new Response("Stale or missing timestamp", { status: 401 });
  }

  // Signed message is "{timestamp}.{raw_body}"
  const expected = crypto
    .createHmac("sha256", process.env.BRICQS_WEBHOOK_SECRET!)
    .update(`${timestamp}.${raw}`)
    .digest("hex");

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const envelope = JSON.parse(raw);

  // Dedupe BEFORE processing: X-Bricqs-Delivery-Id === envelope.id
  const deliveryId = req.headers.get("x-bricqs-delivery-id") ?? envelope.id;
  if (await alreadyProcessed(deliveryId)) return new Response("ok");

  // Acknowledge fast; do real work in a queue.
  await queueForProcessing(envelope);
  return new Response("ok");
}

import hmac, hashlib, time

TOLERANCE_SECONDS = 300

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    ts, signature = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False
    msg = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

A delivery succeeds only on HTTP 2xx within timeout_seconds (default 10).
Anything else (timeout, 4xx, 5xx) schedules a retry:

  attempt 1   immediate
  attempt 2   +30 seconds
  attempt 3   +5 minutes
  attempt 4   +30 minutes
  (attempts = retry_count + 1; retry_count default 3, max 5)

After the last attempt the delivery is EXHAUSTED. Nothing re-sends it
automatically; recover with replay:

  POST /api/v1/gamify/webhooks/{destination_id}/deliveries/{log_id}/replay
  POST /api/v1/gamify/webhooks/{destination_id}/replay        (bulk, returns a job)
  GET  /api/v1/gamify/webhooks/{destination_id}/replay-jobs/{job_id}
  GET  /api/v1/gamify/webhooks/{destination_id}/logs          (delivery history)

Non-guarantees to design around:
  - No ordering, within or across participants.
  - Replayed/retried deliveries can carry "data": {} (redacted). Re-fetch
    GET /api/v1/gamify/state/{participant_id} on replay.
  - No secret rotation endpoint: rotate by delete + recreate.