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

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

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

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

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

أحداث الطلبات​

يمر الطلب بحتى 7 انتقالات حالة في عمره. نُطلق حدثًا واحدًا لكل انتقال، وليس لكل حالة — فتُخطَر كلما تحرّك الطلب.

order.created​

يُطلق عند إنشاء طلب جديد (checkout الواجهة، طلب API، إنشاء يدوي من الإدارة).

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

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" } }

order.delivered​

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

order.cancelled​

يُطلق من أي حالة غير نهائية. إن كان الطلب في حالة مخزون مُلتزَم، يُسترَد المخزون قبل إطلاق هذا الحدث.

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

order.returned​

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

أحداث الدفع​

payment.received​

يُطلق عند وصول دفعة (webhook من SlickPay، إيصال يدوي معتمَد). مستقل عن order.confirmed.

{
  "data": {
    "order_id":  6894,
    "amount":    1000,
    "method":    "slickpay",
    "reference": "TRX-…"
  }
}

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

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​

يُطلق عند تسجيل نداء /v1/events (اختياري حاليًا؛ سيصبح opt-in في v1.1 لتقليل حجم التسليم).

{
  "data": {
    "name":       "lead_submitted",
    "properties": { "form": "footer", "campaign": "spring-2026" }
  }
}

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

product.stock_low​

يُطلق حين track_stock=true و stock_quantity <= low_stock_alert. مرة واحدة لكل عبور-عتبة — لا spam.

{
  "data": {
    "product_id":     26,
    "name":           "T-shirt - Cotton 200gsm",
    "stock_quantity": 4,
    "low_stock_alert": 5
  }
}

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

webhook.test​

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

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

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

Content-Type:    application/json
User-Agent:      dzbuild-webhook/1
X-DZ-Timestamp:  <unix seconds>
X-DZ-Signature:  <hex hmac-sha256>
X-DZ-Delivery-Id: <unique per attempt>

الإصدار​

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

  • event ثابت.
  • قد تظهر حقول جديدة على المستوى الأعلى في data.
  • الأنواع والمعاني الموجودة لن تتغير بدون v2.
  • ترتيب مفاتيح data غير مضمون.