مطوّرو ليتس بيتزاv1.0.0

إشعارات Webhook

إشعارات Webhook

عند وقوع حدث يخص فروعك نرسل طلب HTTPS موقّعاً إلى عنوانك. تحقق من التوقيع، وأجب بسرعة، وتجاهل المكرر.

سير العمل#

  1. ليتس بيتزاوقع حدث (طلب جديد، حالة، إغلاق فرع…)
  2. ليتس بيتزا ← عنوانكطلب POST موقّعX-LP-Signature: v1=…
  3. عنوانكتحقق، واحفظ، وتجاهل المكرر
  4. عنوانك ← ليتس بيتزا2xx خلال 10 ثوانٍ

الأحداث#

الطلبات

الحدثيُرسل عندماdata
order.created وصل طلب جديد إلى الفرع: فوراً للدفع النقدي، وبعد تأكيد مزوّد الدفع للدفع الإلكتروني.{ order }
order.accepted قُبل الطلب.{ order, previousStatus }
order.preparing بدأ المطبخ تحضير الطلب.{ order, previousStatus }
order.ready الطلب جاهز للاستلام أو للمندوب.{ order, previousStatus }
order.out_for_delivery خرج الطلب مع المندوب.{ order, previousStatus }
order.delivered وصل الطلب إلى العميل.{ order, previousStatus }
order.picked_up استلم العميل طلبه من الفرع.{ order, previousStatus }
order.cancelled أُلغي الطلب.{ order, previousStatus }
order.rejected رفض الفرع الطلب.{ order, previousStatus }
order.failed_delivery تعذّر توصيل الطلب.{ order, previousStatus }
order.not_collected لم يحضر العميل لاستلام طلبه.{ order, previousStatus }
order.ack_overdue لم يؤكد نظام الشريك استلام الطلب في المهلة المحددة (settings.orders.ackMinutes).{ order, previousStatus }

المدفوعات

الحدثيُرسل عندماdata
payment.succeeded وصل طلب مدفوع مسبقاً إلى الفرع: إلكترونياً أو عند الكاشير.{ orderId, number, method, tender, amount, paidAt, order }
payment.refunded اكتمل ردّ مبلغ، مع إشعار الدائن إن وُجدت فاتورة.{ orderId, number, refundId, amount, reason, method, settledAt, creditNote }

الفواتير

الحدثيُرسل عندماdata
invoice.issued صدرت الفاتورة المبسّطة مع التوصيل أو الاستلام.{ invoice, orderId, number }

الفروع والتوفّر

الحدثيُرسل عندماdata
branch.closed أغلق الموظفون الفرع مؤقتاً.{ branch, reason, closedAt }
branch.opened أعاد الموظفون فتح الفرع.{ branch, openedAt }
branch.busy بدأ وضع الانشغال أو تغيّر أو أُنهي مبكراً.{ branch, busy }
catalog.published نُشرت نسخة جديدة من المنيو من منيو أرسله الشريك مصدر المنيو.{ versionId, source, partner, changes }
availability.changed أُوقف صنف أو إضافة في فرع أو أُعيد.{ branch, changes }

ping — حدث اختباري يرسله المشرف من لوحة التحكم. { subscriptionId, name, message }

أوقات عمل الفروع (الأسبوعية والأيام الخاصة) ليست أحداثاً: لا يُرسل شيء عند فتح الفرع أو إغلاقه بحسب أوقاته. المبالغ بالهللة، والطلب order بالشكل نفسه في دليل الطلبات.

الطلب#

HTTP
POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: LetsPizza-Webhooks/1
X-LP-Event: order.created
X-LP-Event-Id: 1042.order.created
X-LP-Delivery: 6f3c…
X-LP-Timestamp: 1793350800
X-LP-Signature: v1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46
الترويسةالمعنى
X-LP-Eventنوع الحدث.
X-LP-Event-Idمعرّف الحدث، ثابت في كل إعادة: عليه تمنع التكرار.
X-LP-Deliveryمعرّف هذه المحاولة، يتغيّر عند إعادة الإرسال اليدوية.
X-LP-Timestampوقت التوقيع بثواني Unix.
X-LP-Signatureالتوقيع v1= ثم 64 حرفاً سداسياً.

الغلاف#

JSON
{
  "version": 1,
  "id": "1042.order.created",
  "type": "order.created",
  "occurredAt": "2026-10-30T09:00:00.000Z",
  "branchId": "28",
  "data": {
    "order": {
      "…": "Order"
    }
  }
}
  • version هي 1. قد نضيف حقولاً داخلها، وأي تغيير آخر يأتي بالإصدار 2 بعد إعلان.
  • id ثابت في كل إعادة وإعادة إرسال للحدث نفسه.
  • occurredAt وقت وقوع الحدث، لا وقت إرساله.
  • branchId معرّف الفرع، و null لحدث ping.

التحقق من التوقيع#

  1. خذ جسم الطلب كما وصل بالضبط (بايتات خام) قبل أي تحويل JSON.
  2. احسب HMAC-SHA256 بمفتاح الاشتراك (النص كاملاً كما ظهر لك whsec_…، بترميز UTF-8 دون فك base64) على النص <timestamp>.<raw body>.
  3. اكتب الناتج بأحرف سداسية صغيرة وقبله v1=، وقارنه بالترويسة بمقارنة ثابتة الزمن. قد تحمل الترويسة مستقبلاً عدة قيم مفصولة بفواصل: اقبل إن طابقت إحداها.
  4. ارفض الطلب إذا ابتعد الوقت أكثر من 300 ثانية عن ساعتك (اضبطها على NTP)، وأجب 401 إذا لم يتطابق التوقيع.
import crypto from 'node:crypto';

/**
 * rawBody: the body exactly as received (a Buffer), before any JSON parsing.
 * With Express: app.post('/lp-webhooks', express.raw({ type: 'application/json' }), handler)
 */
export function verifyLpSignature({ secret, timestamp, rawBody, signatureHeader, toleranceSeconds = 300 }) {
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > toleranceSeconds) return false;
  const mac = crypto.createHmac('sha256', Buffer.from(secret, 'utf8'));
  mac.update(`${timestamp}.`, 'utf8');
  mac.update(rawBody);
  const expected = Buffer.from('v1=' + mac.digest('hex'));
  return String(signatureHeader ?? '')
    .split(',')
    .map((s) => Buffer.from(s.trim()))
    .some((candidate) => candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected));
}

متجه الاختبار#

شغّل كودك على هذه القيم: يجب أن يخرج التوقيع نفسه. (تجاوز فحص الوقت هنا، فالوقت قديم عمداً.)

المُدخلالقيمة
secretwhsec_test_vector_not_a_real_secret_0123456789
X-LP-Timestamp1793350800
الجسم الخام{"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}}
X-LP-Signaturev1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46
openssl
printf '%s' '1793350800.{"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}}' \
  | openssl dgst -sha256 -hmac 'whsec_test_vector_not_a_real_secret_0123456789'
# expected hex: eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46

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

المحاولةمتى
1خلال ثوانٍ من وقوع الحدث
2بعد دقيقة واحدة من فشل المحاولة السابقة
3بعد 5 دقائق من فشل المحاولة السابقة
4بعد 30 دقيقة من فشل المحاولة السابقة
5بعد ساعتين من فشل المحاولة السابقة
6 (الأخيرة)بعد 12 ساعة من فشل المحاولة السابقة
  • بعد 6 محاولات فاشلة يُعد الإرسال متوقفاً نهائياً، ويبقى في السجل 30 يوماً قابلاً لإعادة الإرسال.
  • 50 محاولة فاشلة متتالية توقف الاشتراك مؤقتاً: تُحفظ الأحداث ولا تُرسل حتى يُستأنف، ثم تُرسل كلها.
  • الأحداث لا تصل بالترتيب بالضرورة: اعتمد على occurredAt وعلى حالة الطلب وسجله، واعتبر الحالة الأقدم المتأخرة قديمة.

إعادة الإرسال ومنع التكرار#

الإرسال «مرة واحدة على الأقل»: انقضاء المهلة بعد أن عالجت الحدث يبدو لنا فشلاً فنعيده. وإعادة الإرسال من لوحة التحكم ترسل الغلاف نفسه بمعرّف id نفسه، مع X-LP-Delivery جديد.

Node.js
// inside your handler, after verifyLpSignature(...)
const event = JSON.parse(rawBody);
const firstTime = await db.processedEvents.insertIfAbsent(event.id); // unique key on id
if (!firstTime) return res.sendStatus(204);   // a repeat: already handled
res.sendStatus(204);                          // answer first…
await queue.add(event);                       // …work after

اشتراكاتك أنت#

بالصلاحية webhooks:manage تدير اشتراكاتك بنفسك عبر /partner/v1/webhooks: العنوان والأحداث، والسجل، وإعادة الإرسال، وحدث اختبار، وسرّ جديد. الفروع هي فروع مفتاحك، ويصلك من الأحداث ما يخصك فقط:

الأحداثالصلاحية اللازمةما يصلك
order.* · invoice.issuedorders:readالطلبات التي في سحب طلباتك فقط.
payment.*payments:readمدفوعات طلباتك.
catalog.publishedcatalog:readكل نسخة منيو جديدة تُنشر.
branch.* · availability.changedbranches:readفروع مفتاحك.
order.ack_overdueorders:readعن طلباتك أنت فقط: طلب لم تؤكد استلامه في المهلة.

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

البيانات الشخصية#

افتراضياً تصل بيانات العميل مختصرة: الاسم الأول، والجوال مخفي الوسط، والعنوان محذوف. البيانات الكاملة تُفعّل لاشتراك بعينه عند حاجة فعلية (مثل أسطول توصيل)، ويُسجَّل تفعيلها.

قواعد العنوان#

في الإنتاج يجب أن يبدأ العنوان بـ https:// وألا يحمل اسم مستخدم أو كلمة مرور، وأن يشير إلى عنوان عام: العناوين الداخلية والمحلية مرفوضة، ويُعاد الفحص عند كل اتصال.