كل حمولة webhook ملفوفة:

هذه الصفحة توثّق حقل data لكل حدث.

⚠️ تنبيه — أحداث الطلبات في API v1 تتبع حركة الـ API فقط

يُطلق حدث حالة الطلب فقط حين تتغيّر الحالة عبر الـ API — أي PATCH /v1/orders/{id} أو POST /v1/orders/{id}/cancel. أما التأكيد أو الشحن من لوحة تحكم DZBuild، والإرسال الجماعي إلى التوصيل، وتحديثات تتبّع شركة التوصيل التلقائية، فلا تُطلق شيئًا هنا.

كما أن هناك 7 حالات للطلب لكن 5 أحداث حالة فقط: الانتقال إلى pending والانتقال إلى processing لا يُصدران أي شيء إطلاقًا. فقد ينتقل الطلب pending → processing → shipped ولا ترى سوى order.shipped واحدًا.

إن احتجت أحداثًا تغطي كل مصادر الطلبات وكل تغييرات الحالة، استخدم إضافة Webhooks للتاجر على /dashboard/webhooks بدلًا من ذلك — انظر المقارنة في نظرة عامة على Webhooks.

يُطلق فقط للطلبات المُنشأة عبر POST /v1/orders. طلبات واجهة المتجر وصفحات الهبوط والطلبات اليدوية من لوحة التحكم لا تُطلق هذا الحدث — فإن ربطت التنفيذ به ستفوّت الغالبية الساحقة من طلبات التاجر.

هذه المفاتيح الأربعة هي كامل الحمولة. اجلب GET /v1/orders/{id} إن احتجت أي شيء آخر.

يُطلق عند الانتقال إلى confirmed. يُخصم المخزون في هذه اللحظة.

قد تكون old_status حالة لم تُخطَر بها قط — فالانتقال إلى processing في هذا المثال لم يُطلق حدثًا خاصًا به.

يُطلق حين ينتقل الطلب إلى cancelled من pending أو confirmed أو processing — وهذه هي الحالات الوحيدة التي يُسمح بالإلغاء منها. أما POST /v1/orders/{id}/cancel على طلب في حالة shipped أو delivered فيُرجع 400 bad_request ولا يُطلق أي حدث. وإن كان الطلب في حالة مخزون مُلتزَم، يُسترَد المخزون قبل إطلاق هذا الحدث.

محجوز — لا يُصدَر حاليًا. الاسم مقبول في مصفوفة events عند التسجيل ويظهر في allowed_events، لكن لا شيء يُطلقه. تغييرات حالة الدفع لن تصل إلى نقطتك؛ اقرأ GET /v1/orders/{id} إن احتجتها.

يُطلق عند ورود نداء /v1/signups تم احتسابه فعلًا (وليس مكررًا).

لأسباب خصوصية لا نعيد إرسال email ولا phone ولا external_user_id في الـ webhook — أنظمتك تملك هذه القيم أصلًا. الـ webhook إشارة "هذا الاشتراك احتُسب، انقله إلى CRM لديك".

محجوز — لا يُصدَر حاليًا. POST /v1/events يسجّل الحدث ويزيد الاستهلاك، لكنه لا يُطلق أي webhook.

محجوز — لا يُصدَر حاليًا. لا يوجد دفع لتنبيه انخفاض المخزون اليوم.

لكن الحقل الأساسي حقيقي: GET /v1/products/{id} يُرجع low_stock_alert إلى جانب stock_quantity تحت inventory، فيمكنك استعلام الشرط بنفسك.

يُطلق بـ POST /v1/webhooks/{id}/test. يتيح لك التأكد من أن نقطتك قابلة للوصول دون انتظار حدث حقيقي.

لا يمكن الاشتراك فيه — فتضمين webhook.test في مصفوفة events عند التسجيل يُرجع 400 bad_request "unknown event: webhook.test. Allowed: …". ويُسلَّم الاختبار إلى الـ webhook الذي تناديه عليه بغض النظر عن قائمة اشتراكاته.

X-DZ-Delivery-Id هو معرّف تسليم رقمي (مثلًا 4127). وهو ثابت عبر كل إعادة محاولة لذلك التسليم، وهو ليس نفس القيمة delivery_id ذات الـ 16 خانة ست عشرية الموجودة في جسم JSON.

نُضيف أحداثًا جديدة ضمن v1 بحرية (إضافي). عندما نغيّر شكل data لحدث قائم، يكون ذلك تغييرًا يستوجب v2 ويحصل على بادئة مسار جديدة. فيمكن لشيفرتك الاعتماد على: