إنتقل إلى المحتوى الرئيسي

كتالوج الأحداث

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

{
  "event":       "<event name>",
  "store_id":    13,
  "occurred_at": "2026-04-30T21:18:21+00:00",
  "data":        { /* خاص بالحدث، مُوثَّق أدناه */ },
  "delivery_id": "9f2c41ab77e05d18"
}

هذه الصفحة توثّق حقل 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.

order.created​

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

{
  "data": {
    "order_id":       6894,
    "order_number":   "ORD-13-20260317-AD3C",
    "customer_phone": "0555000000",
    "total":          1000
  }
}

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

order.confirmed​

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

{
  "data": {
    "order_id":   6894,
    "old_status": "pending",
    "new_status": "confirmed"
  }
}

order.shipped​

{ "data": { "order_id": 6894, "old_status": "processing", "new_status": "shipped" } }

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

order.delivered​

{ "data": { "order_id": 6894, "old_status": "shipped", "new_status": "delivered" } }

order.cancelled​

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

{ "data": { "order_id": 6894, "old_status": "confirmed", "new_status": "cancelled" } }

order.returned​

{ "data": { "order_id": 6894, "old_status": "delivered", "new_status": "returned" } }

أحداث الدفع​

payment.received​

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

تتبّع الاشتراكات والأحداث​

signup.counted​

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

{
  "data": {
    "key_id":  "dzpub_live_53f32d45fc356",
    "source":  "landing-page-1",
    "country": "DZ"
  }
}

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

event.recorded​

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

أحداث المنتجات​

product.stock_low​

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

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

داخلي / اختبار​

webhook.test​

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

{ "data": { "ts": 1717112657 } }

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

الرؤوس (لكل حدث)​

Content-Type:    application/json
User-Agent:      dzbuild-webhook/1
X-DZ-Timestamp:  <unix seconds>
X-DZ-Signature:  t=<unix seconds>,v1=<hex hmac-sha256>
X-DZ-Delivery-Id: <numeric delivery id>

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

الإصدار​

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

  • event ثابت.
  • قد تظهر حقول جديدة على المستوى الأعلى في data.
  • الأنواع والمعاني الموجودة لن تتغير بدون v2.
  • ترتيب مفاتيح data غير مضمون.
هذه الصفحة لأدوات الذكاء الاصطناعيعرض بصيغة Markdownفتح في ChatGPTفتح في Claude