الويب هوك

الغلاف

كل حدث كائن JSON واحد. id فريد لكل حدث وهو مفتاح إزالة التكرار؛ وfamily تجمع الأنواع المتقاربة (order، payment، subscription، gateway)؛ وdata تحمل حمولة النوع.

{
  "id": "01J8…",
  "version": 1,
  "family": "order",
  "type": "order.placed",
  "occurred_at": "2026-09-26T02:00:00Z",
  "tenant_id": "01HZ…",
  "data": { … }
}

التوقيعات

كل تسليم موقَّع: HMAC-SHA256 على جسم الطلب الخام بالترميز السداسي، في X-Commerce-Signature لأحداث الطلبات وX-Pay-Signature لأحداث المدفوعات، بصيغة sha256=<hex>. لا يُرسَل جسم بلا توقيع أبدًا. تحقَّق بإعادة الحساب على البايتات المستلمة نفسها — قبل تحليل JSON — وبمقارنة بزمن ثابت.

signature = request.headers["X-Commerce-Signature"]  // "sha256=<hex>"
expected  = "sha256=" + hmac_sha256_hex(secret, raw_request_body)
valid     = constant_time_equal(signature, expected)

التسليم

• مرة على الأقل: قد يصل الحدث نفسه مرتين. أزل التكرار على id.
• التسليم الفاشل يُعاد بتباعد أُسّي، بحدّ ساعة بين المحاولات.
• أجب بـ 2xx بسرعة ثم اعمل بعدها؛ فالمعالج البطيء يُقرأ فشلًا ويُعاد إرساله.

الاشتراكات

تسجيل نقطة استقبال خاصة بك — تختار عائلات الأحداث التي تريدها، وتستقبلها على عنوانك، وتتحقق بسرّ خاص بالاشتراك — جزء من إصدار الويب هوك العام المخطط له. لا يوجد مسار اشتراك بعد؛ وحين يصدر سيوثَّق هنا، والغلاف ونظام التوقيع أعلاه هما ما سيكون معالجك مكتوبًا عليه سلفًا.

أنواع أحداث الطلبات

• order.placed
• order.payment_state_changed
• order.fulfilment_state_changed
• order.return_state_changed
• order.cancelled