تخطَّ إلى المحتوى
مطوّرو دكانالتوثيق
Englishتسجيل الدخول

أحداث Webhooks

كل موضوع يمكن لتطبيقك الاشتراك فيه، والنطاق الذي يتطلبه، والغلاف المشترك بين كل عمليات التسليم.

في هذه الصفحة

غلاف التسليم

Delivered for every subscribed topic. Verify X-Dukkan-Hmac-Sha256 (hex HMAC-SHA256 of {X-Dukkan-Timestamp}.{raw body} with the signing secret of the install named in the signed install_id), reject timestamps older than five minutes, deduplicate on the signed envelope id, and refuse a store_id that differs from the install you hold. sequence is strictly increasing per store with gaps — order by it, never count on contiguity. Topics require the matching granted scope (see x-dukkan-topic-scopes); app.uninstalled needs no scope and still delivers after revocation. Respond 2xx with a small body within the timeout; anything else is retried with exponential backoff up to 8 attempts, after which the delivery is dead-lettered and sustained failures disable the subscription. Sandbox rehearsals fired through POST /webhooks/test carry test: true.

الترويسات

الاسمالنوعالوصف
X-Dukkan-Delivery-Idheaderمطلوبstring

Delivery attempt id (unsigned; retries reuse it)

X-Dukkan-Install-Idheaderمطلوبstring

Unsigned hint of the signed envelope install_id

X-Dukkan-EventheaderمطلوبWebhookTopic

Webhook topic. Subscribing needs the read scope that governs the payload; app.uninstalled needs none and still delivers after revocation.

X-Dukkan-Timestampheaderمطلوبstring

Unix seconds

X-Dukkan-Api-Versionheaderمطلوبstring

Dated v1 revision that produced this payload

X-Dukkan-Hmac-Sha256headerمطلوبstring

جسم الطلب

الاسمالنوعالوصف
idمطلوبstring

Event id. Deduplicate on this signed value, never on the delivery header.

api_versionمطلوب"v1"
topicمطلوبWebhookTopic

Webhook topic. Subscribing needs the read scope that governs the payload; app.uninstalled needs none and still delivers after revocation.

القيم:order.createdorder.status_changedorder.paidproduct.createdproduct.updatedproduct.deletedinventory.movement_createdfulfillment.requestedfulfillment.createdfulfillment.updatedrefund.createdapp.uninstalled
store_idمطلوبstring
install_idمطلوبstring

The install this delivery was fanned out to. Verify the signature with THIS install's secret and refuse a store mismatch.

sequenceمطلوبinteger

Strictly increasing per store with gaps. Order by it; never count on contiguity.

occurred_atمطلوبstring
testboolean

Present and true only for sandbox test deliveries (POST /webhooks/test). Absent in production traffic.

dataمطلوبobject
مثال
{
  "id": "9b2f6c1e-7d3a-4f0b-9a52-1c8e2d4b6a70",
  "api_version": "v1",
  "topic": "order.created",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "sequence": 1661,
  "occurred_at": "2026-08-18T16:00:00.123Z",
  "data": {
    "order_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "order_number": "1042",
    "status": "placed",
    "total_minor": 275000,
    "currency": "SYP"
  }
}

order.created#

النطاق:orders:read

إنشاء طلب من أي مصدر.

مثال الحمولة
{
  "id": "9b2f6c1e-7d3a-4f0b-9a52-1c8e2d4b6a70",
  "api_version": "v1",
  "topic": "order.created",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "sequence": 1661,
  "occurred_at": "2026-08-18T16:00:00.123Z",
  "data": {
    "order_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "order_number": "1042",
    "status": "placed",
    "total_minor": 275000,
    "currency": "SYP"
  }
}

order.status_changed#

النطاق:orders:read

كل انتقال في حالة الطلب.

لا مثال لهذا الموضوع بعد.

order.paid#

النطاق:orders:read

عندما تعبر المبالغ المحصَّلة فعلاً إجمالي الطلب في دفتر المدفوعات.

لا مثال لهذا الموضوع بعد.

product.created#

النطاق:products:read

إنشاء منتج.

لا مثال لهذا الموضوع بعد.

product.updated#

النطاق:products:read

تغيّر منتج أو أحد متغيراته.

لا مثال لهذا الموضوع بعد.

product.deleted#

النطاق:products:read

حذف منتج.

لا مثال لهذا الموضوع بعد.

inventory.movement_created#

النطاق:inventory:read

حركة مخزون جديدة.

مثال الحمولة
{
  "movement_id": "0a1b2c3d-0001-4e8f-9b70-2d1c3e4f5a6b",
  "variant_id": "c0ffee00-0001-4e8f-9b70-2d1c3e4f5a6b",
  "location_id": "10c00000-0001-4e8f-9b70-2d1c3e4f5a6b",
  "delta": -2,
  "stock_after": 23,
  "reason": "damage"
}

fulfillment.requested#

النطاق:orders:read

إنشاء شحنة بحالة pending: طلب حجز مندوب.

لا مثال لهذا الموضوع بعد.

fulfillment.created#

النطاق:orders:read

إنشاء أي شحنة.

لا مثال لهذا الموضوع بعد.

fulfillment.updated#

النطاق:orders:read

تغيّر حالة الشحنة أو رقم تتبعها.

لا مثال لهذا الموضوع بعد.

refund.created#

النطاق:orders:read

تسجيل استرداد.

لا مثال لهذا الموضوع بعد.

app.uninstalled#

النطاق:لا يتطلب نطاقاً

إلغاء التثبيت؛ يصل حتى بعد إلغاء الرموز.

لا مثال لهذا الموضوع بعد.