Webhooks والتوقيعWebhooks and signatures

{
  "url": "https://hooks.example.com/zahif",
  "headers": {
    "X-Project": "aleem"
  },
  "metadata": {
    "run": 42
  },
  "events": [
    "page",
    "completed",
    "failed"
  ]
}

كل تسليم يحمل X-Zahif-Signature بالقيمة sha256=<hex>. احسب HMAC بسرّ الـ webhook وقارن بزمن ثابت.Every delivery carries X-Zahif-Signature with the value sha256=<hex>. Compute the HMAC with your webhook secret and compare in constant time.

احصل على سرّ مفتاحك من GET /v2/zahif/webhook-secret.Get your key's secret from GET /v2/zahif/webhook-secret.

// Node / Workers
async function verify(raw: string, header: string, secret: string) {
  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw)));
  const hex = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
  const got = header.replace(/^sha256=/, "");
  if (got.length !== hex.length) return false;
  let diff = 0;
  for (let i = 0; i < hex.length; i++) diff |= hex.charCodeAt(i) ^ got.charCodeAt(i);
  return diff === 0;
}

# Python
import hmac, hashlib
def verify(raw: bytes, header: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, header.removeprefix("sha256="))

يُعاد التسليم عند الفشل بفواصل متزايدة؛ اجعل المستقبِل متسامحاً مع التكرار عبر id ونوع الحدث.Failed deliveries are retried with backoff; make your receiver idempotent on id plus event type.