الويبهوكس

بدل استطلاع نقاط النهاية دوريًا، يرسل منفذ إشعارًا فوريًا إلى خادمك عند كل حدث مهم في شحناتك.

إعداد نقطة الاستقبال

سجّل عنوان HTTPS يستقبل الإشعارات عبر POST /api/v1/webhooks/config. حدّد الأحداث التي تهمك، أو أغفل الحقل events لتستقبلها جميعًا:

curl -s -X POST "https://manfath.example/api/v1/webhooks/config" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.sa/manfath/hook",
  "events": ["shipment.status_updated", "shipment.exception"]
}'

تعيد الاستجابة سرّ الويبهوك الخاص بفريقك — خزّنه في مكان آمن فهو أساس التحقق من صحة الإشعارات:

{
  "url": "https://example.sa/manfath/hook",
  "events": ["shipment.status_updated", "shipment.exception"],
  "secret": "whsec_9f2c4a7d1e8b3f6c5a0d9e2b4c7f1a3d"
}

الأحداث

شكل التسليم

يصل كل إشعار طلب POST بجسم JSON وترويستين مميزتين: X-Manfath-Event باسم الحدث، و X-Manfath-Signature بتوقيع الحمولة. مثال إشعار تغيير حالة:

POST /manfath/hook HTTP/1.1
Content-Type: application/json
X-Manfath-Event: shipment.status_updated
X-Manfath-Signature: ...

{
  "event": "shipment.status_updated",
  "tracking_number": "SRE0248817359",
  "manfath_reference": "MNF-2026-K7Q2ZC",
  "status": "IN_TRANSIT",
  "status_ar": "في الطريق",
  "status_en": "In transit",
  "location_ar": "الرياض",
  "location_en": "Riyadh",
  "occurred_at": "2026-07-26T18:40:00+03:00",
  "is_exception": false
}

إعادة المحاولة

يعتبر منفذ التسليم ناجحًا عند أي استجابة 2xx خلال 10 ثوانٍ. عند الفشل — مهلة منتهية أو رمز غير 2xx — يعيد المحاولة وفق الجدول:

بعد 5 ثوانٍ، ثم 30 ثانية، ثم دقيقتين، ثم 10 دقائق، ثم ساعة.

بعد استنفاد المحاولات الخمس يتوقف الإرسال لذلك الإشعار. أعد الاستجابة بسرعة: أكّد الاستلام فورًا بـ 200 وأجّل المعالجة الثقيلة إلى ما بعد الرد.

الأمان

وقّع الحمولة بمفتاحك السري باستخدام HMAC SHA-256 وتحقق من ترويسة X-Manfath-Signature. تجاهل أي إشعار لا يجتاز التحقق.

صندوق الاستقبال المستضاف

ليس لديك خادم عام بعد؟ يوفر منفذ صندوق استقبال جاهزًا لكل فريق على المسار:

https://manfath.example/hook/TEAMCODE

وجّه إعداد الويبهوك إليه (استبدل TEAMCODE برمز فريقك)، ثم راجع كل طلب وصل — بترويساته وجسمه — من فاحص الويبهوكس في لوحة التحكم. وهو طريقة ممتازة لفحص شكل الإشعارات قبل بناء نقطة الاستقبال الحقيقية. لتطبيق يعمل محليًا على جهازك: إما عرّضوا منفذكم المحلي عبر نفق (ngrok أو ما يماثله) ووجّهوا الويبهوك إليه، أو استعلموا عن الصندوق المستضاف برمجيًا عبر GET /api/v1/webhooks/inbox — يعيد الطلبات الأخيرة بجسمها الخام فتستطيعون التحقق من التوقيع في كودكم دون خادم عام.