GROperator

جارٍ التحميل…

English

الـ Webhooks

الـ Webhooks تجعل LastMile تستدعي خادمك حين يحدث شيء للشحنة، فلا تحتاج إلى الاستعلام المتكرر. استخدمها لإبقاء حالة الطلب في نظامك محدّثة ولإشعار عملائك.

النطاق: webhooks:manage. الاشتراك يتبع تاجراً واحداً ويستقبل أحداث شحنات ذلك التاجر.

POST /merchants/{merchantId}/webhooks:

الحقل التفاصيل
url مطلوب. عنوان https عام يستقبل الأحداث. العناوين المحلية والخاصة تُرفض (security.unsafe_webhook_target_url وintegrations.invalid_target_url)
events مطلوب، حدث واحد على الأقل. أنواع الأحداث من الجدول أدناه، أو الرمزان shipment.* (كل أحداث الشحنة) و* (كل شيء)
description نص اختياري لتمييز الاشتراك، حتى 200 محرف
POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/hooks/lastmile",
  "events": [
    "shipment.created",
    "shipment.out_for_delivery",
    "shipment.delivered"
  ],
  "description": "Order system"
}'
JSON
{
  "id": "c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://shop.example.com/hooks/lastmile",
  "events": [
    "shipment.created",
    "shipment.out_for_delivery",
    "shipment.delivered"
  ],
  "description": "Order system",
  "isActive": true,
  "createdAt": "2026-01-15T09:00:00Z",
  "secret": "5f1c0a7e9d3b..."
}

يحتوي الرد على secret التوقيع. يظهر مرة واحدة هنا: خزّنه كسر على خادمك. ولتحصل على سر جديد دوّره بـ POST /merchants/{merchantId}/webhooks/{id}/rotate-secret؛ والسر القديم يتوقف فوراً.

العملية ما تفعله
GET /merchants/{merchantId}/webhooks يعرض اشتراكات التاجر (بلا أسرار)
POST /merchants/{merchantId}/webhooks/{id}/test يضع في الطابور إرسال ping موقّعاً إلى العنوان كأنه حدث حقيقي. الاشتراكات الفعّالة فقط تُختبر
POST /merchants/{merchantId}/webhooks/{id}/rotate-secret يرجع سراً جديداً يظهر مرة واحدة
DELETE /merchants/{merchantId}/webhooks/{id} يحذف الاشتراك. سجلات الإرسال السابقة تبقى
GET /webhooks/events فهرس الأحداث الحي مع الأوصاف وأمثلة الحمولة
POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"
الحدثيُرسل عندمااسم الحالة في الحمولة
shipment.createdأُنشئت شحنة (من لوحة التحكم أو استيراد أو الـ API).Created
shipment.picked_upاستلم المندوب الشحنة من المرسل.PickedUp
shipment.out_for_deliveryخرجت الشحنة للتوصيل مع مندوب.OutForDelivery
shipment.deliveredسُلّمت الشحنة (كلياً أو جزئياً).Delivered
shipment.cancelledأُلغيت الشحنة.Cancelled
shipment.on_holdالشحنة محتجزة في المستودع.OnHoldWarehouse
shipment.lostأُعلنت الشحنة مفقودة.Lost
shipment.damagedأُعلنت الشحنة تالفة.Damaged
shipment.ndr_createdفشلت محاولة توصيل (تقرير عدم التسليم).DeliveryAttempted
shipment.rto_initiatedبدأت الشحنة رحلة العودة إلى المرسل.RTOInitiated
shipment.rto_received_at_warehouseاستُلمت الشحنة المرتجعة في المستودع.RTOInitiated
shipment.rto_out_for_returnالشحنة المرتجعة في طريقها إلى المرسل.RTOInTransit
shipment.rto_refused_by_merchantرفض التاجر الشحنة المرتجعة.RTOInTransit
shipment.returned_to_merchantسُلّمت الشحنة إلى التاجر.ReturnedToSender

الحدث ping يُرسل من نقطة الاختبار فقط ولا يمكن الاشتراك فيه. والفهرس يقدمه أيضاً GET /webhooks/events مباشرة.

كل إرسال هو POST إلى عنوانك بجسم JSON بالشكل { "event", "occurredAt", "data" }:

JSON
{
  "event": "shipment.delivered",
  "occurredAt": "2026-01-15T09:30:00Z",
  "data": {
    "trackingNumber": "AWB-RUH-000123",
    "statusCode": 4040,
    "statusName": "Delivered",
    "trackUrl": "https://tracking.example.com/track/AWB-RUH-000123",
    "awbUrl": "https://tracking.example.com/awb/AWB-RUH-000123",
    "rtoTrackingNumber": null
  }
}
الحقل المعنى
event نوع الحدث
occurredAt وقت حدوثه، ISO 8601 بتوقيت UTC
data.trackingNumber الشحنة. اجلب GET /shipments/{trackingNumber} إن احتجت تفاصيل أكثر
data.statusCode وdata.statusName الحالة التي سببت الحدث (اسم الـ enum مثل Delivered)
data.trackUrl وdata.awbUrl رابطا صفحة التتبع العامة والبوليصة
data.rtoTrackingNumber رقم تتبع شحنة الإرجاع إن وُجدت؛ وإلا null

ويحمل الطلب الترويسات التالية:

الترويسة القيمة
X-Event-Type نوع الحدث مكرراً من الجسم
X-Signature التوقيع بنظام سداسي عشري بأحرف صغيرة
X-Webhook-Signature القيمة نفسها لـ X-Signature

التوقيع هو hex(HMAC_SHA256(secret, rawBody)): ناتج HMAC-SHA256 بنظام سداسي عشري بأحرف صغيرة على جسم الطلب الخام (البايتات نفسها كما وصلت) بمفتاح هو سر الاشتراك. تحقق منه دائماً قبل أن تثق بالإرسال.

  1. اقرأ الجسم الخام قبل أي تحليل JSON. إعادة تسلسل JSON المحلَّل تغيّر البايتات وتكسر الفحص.
  2. احسب HMAC بالسر.
  3. قارنه مع X-Signature بزمن ثابت (constant time).
  4. ارفض الطلب بـ 401 إن لم يتطابق.
// Node.js + Express. The webhook secret comes from the environment.
import crypto from "node:crypto";
import express from "express";

const app = express();

// Keep the raw bytes: the signature is computed over them, not over parsed JSON.
app.post("/hooks/lastmile", express.raw({ type: "application/json" }), (req, res) => {
  const received = String(req.get("X-Signature") ?? "");
  const expected = crypto
    .createHmac("sha256", process.env.LASTMILE_WEBHOOK_SECRET)
    .update(req.body) // a Buffer
    .digest("hex");

  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // Store the event, answer quickly, work later.
  console.log(event.event, event.data.trackingNumber, event.data.statusName);
  res.sendStatus(200);
});

app.listen(3000);

ردّ بأي حالة 2xx بمجرد تخزين الحدث، وأجّل العمل البطيء. أي حالة أخرى أو انتهاء مهلة أو خطأ اتصال يُعدّ فشلاً ويُعاد الإرسال بعد دقيقة و5 دقائق و15 دقيقة. وبعد ذلك لا يُرسَل ثانية، فإن كان خادمك متوقفاً طويلاً فطابق الحالات عبر GET /shipments.

ولأجل إعادة المحاولة والشبكة، استعد لما يلي:

  • التكرار. قد يصل الحدث نفسه أكثر من مرة. اجعل معالجك آمناً للتكرار، مثلاً بتذكّر event + data.trackingNumber + occurredAt.
  • وصول غير مرتب. استخدم occurredAt أو اجلب الشحنة، ولا تفترض أن آخر حدث وصل هو الأحدث.
  • إعادة الإرسال المتعمدة. التوقيع يغطي الجسم ومنه occurredAt. إن أردت رفض الإرسالات القديمة جداً فقارنه بساعتك.
  • العنوان https عام.
  • السر مخزّن على الخادم ولا يُكتب في السجلات.
  • التوقيع يُفحص على الجسم الخام بزمن ثابت.
  • المعالج يرد 2xx بسرعة وهو آمن للتكرار.
  • اختبرته بـ POST .../test.