Webhooks

عندما يكون التطبيق في وضع HIOBuy warehouse fulfillment، يدفع HIOBuy أحداث دورة حياة الوفاء إلى نقطة نهاية HTTPS لديك. اضبطها من Developer Portal → Webhooks . التسليم غير متزامن؛ استجابات Public API لا تنتظر خادم Webhook.

متطلب أساسي: تفويض القناة → وضع الوفاء = HIOBuy warehouse. في وضع self تظهر المقدمة فقط ولا يمكن إنشاء/تفعيل Endpoint.

نظرة عامة {#overview}

التسجيل وتدوير السر وسجل التسليم وإعادة المحاولة اليدوية عبر البوابة فقط (مصادقة الجلسة). لا توجد واجهة Public /v1/webhooks/* في v1.

كتالوج الأحداث {#events}

اشترك لكل endpoint. يلزم حدث واحد على الأقل.

دفع live من المستودع إلى المطوّر يُطرح تدريجيًا؛ استخدم Send test الآن للتحقق من المستقبل.

الغلاف العام {#envelope}

جسم كل تسليم هو JSON:

{
  "id": "evt_01HXYZ…",
  "type": "package.received",
  "created_at": "2026-08-16T04:00:00.000Z",
  "livemode": true,
  "app_id": "app_…",
  "data": {
    "package_id": "pkg_…",
    "order_id": "ord_…",
    "status": "received"
  }
}

أمثلة data {#data-shapes}

مطابقة لعينات اختبار البوابة؛ المباشر يستخدم نفس المفاتيح.

procurement.failed

{
  "order_id": "ord_…",
  "status": "failed",
  "reason": "supplier_rejected"
}

package.exception

{
  "package_id": "pkg_…",
  "order_id": "ord_…",
  "status": "exception",
  "exception_type": "DAMAGED"
}

shipment.dispatched

{
  "shipment_id": "shp_…",
  "tracking_number": "…",
  "status": "dispatched"
}

balance.low

{
  "available_amount": 12.5,
  "currency": "USD",
  "threshold": 50
}

تسليم HTTP {#delivery}

POST /your/webhook-path HTTP/1.1
Host: your-server.example
Content-Type: application/json
User-Agent: HioBuy-Webhooks/1.0
HioBuy-Event-Id: evt_01HXYZ…
HioBuy-Signature: t=1723780800,v1=abcdef0123456789…

• في الإنتاج يجب أن يكون عنوان URL بـ HTTPS. خارج الإنتاج قد يُسمح بـ http://localhost / الأنفاق.
• أجب بـ 2xx خلال 10 ثوانٍ. غير ذلك يجدول إعادة محاولة.
• التسليم مرة واحدة على الأقل. أزل التكرار عبر id (واختياريًا HioBuy-Event-Id).

التحقق من التوقيع {#signature}

1. اقرأ HioBuy-Signature (t=<unix_seconds>,v1=<hex_hmac>).
2. ابنِ "{t}.{raw_body}" حيث raw_body هو الجسم الخام كما استُلم (JSON UTF-8).
3. احسب HMAC-SHA256(secret, signed_payload) بصيغة hex.
4. قارن مع v1 بمقارنة زمن ثابت.
5. ارفض إذا كان |now - t| كبيرًا جدًا (تسامح مُوصى به: 5 دقائق).

Node.js مثال

import crypto from "node:crypto";
 
function verifyHioBuySignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]+)$/i.exec(signatureHeader || "");
  if (!match) return false;
 
  const t = Number(match[1]);
  const expected = match[2].toLowerCase();
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
 
  const signed = `${t}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", secret)
    .update(signed, "utf8")
    .digest("hex");
 
  const a = Buffer.from(digest, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

خزّن whsec_… على الخادم فقط. تعرض البوابة قناعًا (آخر 6). بعد التدوير حدّث الخادم قبل التسليم التالي.

إعادة المحاولة وحالة التسليم {#retries}

بعد آخر فشل تصبح الحالة failed. يمكن Retry now من تفاصيل البوابة.

الحالات: pending · success · retrying · failed.

سير عمل البوابة {#portal}

1. اضبط التطبيق على warehouse fulfillment في Channel Auth / setup.
2. افتح Webhooks  → Add endpoint.
3. أدخل عنوان HTTPS ووصفًا اختياريًا والأحداث.
4. انسخ سر التوقيع فور ظهوره (مرة واحدة).
5. استخدم Send test event وافحص deliveries / attempts.
6. دوّر السر أو عطّل أو احذف عند الحاجة.

الحدود والاحتفاظ {#limits}

ذات صلة

• Fulfillment setup — وضع المستودع
• Fulfillment API — مسارات الشحن الدولي
• Authentication — مفاتيح API (منفصلة عن سر Webhook)
• Sandbox — طلبات sandbox لا تُدفع تلقائيًا؛ استخدم Send test