إشعارات Webhook
إشعارات Webhook
عند وقوع حدث يخص فروعك نرسل طلب HTTPS موقّعاً إلى عنوانك. تحقق من التوقيع، وأجب بسرعة، وتجاهل المكرر.
سير العمل#
- ليتس بيتزاوقع حدث (طلب جديد، حالة، إغلاق فرع…)
- ليتس بيتزا ← عنوانكطلب POST موقّع
X-LP-Signature: v1=… - عنوانكتحقق، واحفظ، وتجاهل المكرر
- عنوانك ← ليتس بيتزا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 بالشكل نفسه في دليل الطلبات.
الطلب#
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 حرفاً سداسياً. |
الغلاف#
{
"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.
التحقق من التوقيع#
- خذ جسم الطلب كما وصل بالضبط (بايتات خام) قبل أي تحويل JSON.
- احسب HMAC-SHA256 بمفتاح الاشتراك (النص كاملاً كما ظهر لك
whsec_…، بترميز UTF-8 دون فك base64) على النص<timestamp>.<raw body>. - اكتب الناتج بأحرف سداسية صغيرة وقبله
v1=، وقارنه بالترويسة بمقارنة ثابتة الزمن. قد تحمل الترويسة مستقبلاً عدة قيم مفصولة بفواصل: اقبل إن طابقت إحداها. - ارفض الطلب إذا ابتعد الوقت أكثر من 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));
}متجه الاختبار#
شغّل كودك على هذه القيم: يجب أن يخرج التوقيع نفسه. (تجاوز فحص الوقت هنا، فالوقت قديم عمداً.)
| المُدخل | القيمة |
|---|---|
| secret | whsec_test_vector_not_a_real_secret_0123456789 |
X-LP-Timestamp | 1793350800 |
| الجسم الخام | {"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}} |
X-LP-Signature | v1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46 |
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 جديد.
// 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.issued | orders:read | الطلبات التي في سحب طلباتك فقط. |
payment.* | payments:read | مدفوعات طلباتك. |
catalog.published | catalog:read | كل نسخة منيو جديدة تُنشر. |
branch.* · availability.changed | branches:read | فروع مفتاحك. |
order.ack_overdue | orders:read | عن طلباتك أنت فقط: طلب لم تؤكد استلامه في المهلة. |
وتصل بيانات العميل كاملة أو مختصرة بحسب إعداد settings.customerData الحالي لدى ليتس بيتزا، لا بحسب طلب الاشتراك. يظهر سرّ التوقيع مرة واحدة عند الإنشاء؛ إن ضاع فاطلب سرّاً جديداً.
البيانات الشخصية#
افتراضياً تصل بيانات العميل مختصرة: الاسم الأول، والجوال مخفي الوسط، والعنوان محذوف. البيانات الكاملة تُفعّل لاشتراك بعينه عند حاجة فعلية (مثل أسطول توصيل)، ويُسجَّل تفعيلها.
قواعد العنوان#
في الإنتاج يجب أن يبدأ العنوان بـ https:// وألا يحمل اسم مستخدم أو كلمة مرور، وأن يشير إلى عنوان عام: العناوين الداخلية والمحلية مرفوضة، ويُعاد الفحص عند كل اتصال.