Webhooks

{
  "event_id": "evt_01J9ZQ3M4N5P6R7S8T9V0W1X2Y",
  "type": "job.completed",
  "occurred_at": "2026-09-28T10:00:00Z",
  "organization_id": "org_01J9ZQ3M4N5P6R7S8T9V0W1X2Y",
  "workspace_id": "ws_01J9ZQ3M4N5P6R7S8T9V0W1X2Y",
  "correlation_id": null,
  "api_version": "v1",
  "attempt": 1,
  "data": { "job_id": "job_01J9ZQ3M4N5P6R7S8T9V0W1X2Y", "status": "completed" }
}

signed_payload = "<t>" + "." + <raw request body>
v1 = hex( HMAC-SHA256( key = your secret, "whsec_…", as UTF-8,
                       message = signed_payload ) )

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    """True if an AkilIQ webhook is authentic and recent.

    raw_body: the request body exactly as received, before any JSON parsing.
    signature_header: the X-AkilIQ-Signature header, "t=<unix>,v1=<hex>[,v1=<hex>]".
    secret: the endpoint's signing secret, "whsec_...".
    """
    timestamp, signatures = None, []
    for part in signature_header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not signatures:
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False  # too old (or too far ahead): a replayed or delayed request
    signed = str(timestamp).encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, candidate) for candidate in signatures)

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

// rawBody: the request body exactly as received (a Buffer), before JSON parsing.
// signatureHeader: the X-AkilIQ-Signature header, "t=<unix>,v1=<hex>[,v1=<hex>]".
// secret: the endpoint's signing secret, "whsec_...".
export function verifyWebhook(rawBody, signatureHeader, secret) {
  let timestamp = null;
  const signatures = [];
  for (const part of signatureHeader.split(",")) {
    const [key, value = ""] = part.trim().split("=", 2);
    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
    else if (key === "v1") signatures.push(value);
  }
  if (timestamp === null || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  return signatures.some((candidate) => {
    const given = Buffer.from(candidate, "hex");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}