الويب هوك (Webhooks)

يتيح الويب هوك لتطبيقك استقبال إشعارات لحظية عند وقوع الأحداث في متجرك — بدل الاستعلام المتكرر من الـ API عن التغييرات. فعند إنشاء طلب أو دفعه أو تجهيزه أو تعديله، ترسل TakeTheme طلب POST إلى عنوان تتحكم فيه، يحمل وصفًا للحدث بصيغة JSON.

استخدم الويب هوك لإبقاء الأنظمة الخارجية متزامنة مع TakeTheme: تحديث نظام ERP أو المحاسبة عند دفع الطلبات، أو بدء التجهيز في منصة المخازن، أو إشعار قناة على Slack، أو تحديث لوحة معلومات يراها العملاء.

كيف يعمل

1. تسجّل عنوانًا أو أكثر — روابط HTTPS على خادمك تستقبل الأحداث.
2. تختار لكل عنوان الأحداث التي يشترك بها (مثل order.paid).
3. عند وقوع حدث مشترَك به، تسلّم TakeTheme حمولة JSON موقّعة إلى عنوانك.
4. يتحقق عنوانك من التوقيع، وينفّذ عمله، ويردّ برمز حالة 2xx.
5. وإذا تعذّر الوصول إلى عنوانك أو أعاد رمزًا غير 2xx، تعيد TakeTheme المحاولة بفواصل متزايدة.

  حدث في المتجر              TakeTheme                     خادمك
 ─────────────      ─────────────────────────      ───────────────────────
  order.paid  ───▶   توقيع + إرسال الحمولة ───▶   التحقق من التوقيع
                                                   معالجة الحدث
                     تسجيل التسليم       ◀───   الرد بـ 200 OK

المتطلبات

متطلب الباقة

الويب هوك متاح في الباقات التي تشمل الوصول إليه (canAccessWebhooks). وإذا كانت باقتك الحالية لا تشمله، تُعيد طلبات إدارة العناوين الرمز 403 Forbidden. راجع صفحة الفوترة في لوحة التحكم للترقية.

يجب أن يكون العنوان المستقبِل:

• مُقدَّمًا عبر HTTPS — تُرفض روابط http:// العادية.
• متاحًا للوصول العام. تُحظر عناوين IP الداخلية أو الخاصة (loopback وlink-local والنطاقات الخاصة) منعًا لهجمات SSRF.
• بلا إعادة توجيه. لا تُتبَّع عمليات إعادة التوجيه (3xx) — ردّ من رابط العنوان مباشرة.
• قادرًا على الرد خلال 10 ثوانٍ برمز حالة 2xx.

الأحداث المتاحة

تُصدر TakeTheme حاليًا أحداث دورة حياة الطلب:

الحدث	يُرسَل عندما…
order.placed	يُنشأ طلب جديد.
order.paid	يُحصَّل مبلغ الطلب أو يُعلَّم كمدفوع.
order.fulfilled	يُعلَّم الطلب (أو ما تبقّى من عناصره) كمُجهَّز.
order.cancelled	يُلغى الطلب.
order.returned	يُعلَّم الطلب كمرتجع.
order.refunded	يُسترد مبلغ الطلب.
order.updated	يُعدَّل الطلب أو تُسوَّى حالته (مع تجميع الدفعات — انظر أدناه).

يشترك كل عنوان بحدث واحد على الأقل. راجع مرجع الأحداث للاطلاع على حمولة كل حدث كاملة.

الحدث order.updated مُجمَّع

قد يُصدر إجراء إداري واحد (تعديل طلب، أو تسوية التجهيز أو الدفع) إشارات order.updated داخلية كثيرة. لذا تجمع TakeTheme هذه الدفعة في تسليم واحد لكل طلب خلال نافذة قصيرة (نحو 5 ثوانٍ). أما أحداث دورة الحياة (order.paid وorder.fulfilled وغيرها) فلا تُجمَّع أبدًا — تستقبل تسليمًا واحدًا لكل وقوع.

بنية الحمولة

كل حمولة ويب هوك هي غلاف JSON بالبنية العليا نفسها مهما كان نوع الحدث:

{
  "id": "3f1c2b9e-8a4d-4c7e-9b1a-2d6f8e0c1a34",
  "type": "order.paid",
  "created": 1751371200.123,
  "data": {
    "object": {
      "id": "665f1b2c9a3e4d0012ab34cd",
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "unfulfilled",
      "totalPrice": 349.99,
      "currency": "EGP",
      "customer": { "...": "..." },
      "items": [ { "...": "..." } ],
      "shippingAddress": { "...": "..." },
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  }
}

الحقل	النوع	الوصف
id	نص	معرّف التسليم/الحدث الفريد (UUID). يطابق ترويسة X-TakeTheme-Delivery. استخدمه لإسقاط المكرر.
type	نص	نوع الحدث، مثل order.paid.
created	رقم	طابع زمني Unix (بالثواني مع الكسور) للحظة إنشاء الحدث.
data.object	كائن	المورد الذي يخصّه الحدث — وهو كائن الطلب في أحداث الطلبات.

الحقل created ليس الطابع الزمني للتوقيع

يصف الحقل created وقت وقوع الحدث. أما الطابع الزمني المستخدم في التحقق من التوقيع فيأتي منفصلًا في ترويسة X-TakeTheme-Signature (t=…). تحقّق دائمًا من الطابع الزمني في الترويسة لا من created. راجع التحقق من التواقيع.

البداية السريعة

1. أنشئ عنوانًا

سجّل رابط HTTPS واشترك به في الأحداث. يمكنك ذلك من لوحة التحكم (الإعدادات ← الويب هوك) أو عبر الـ API:

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/taketheme",
    "events": ["order.placed", "order.paid", "order.fulfilled"],
    "description": "Production order sync"
  }'

تتضمن الاستجابة مفتاح توقيع يُعرض لمرة واحدة (whsec_…). احفظه في مكان آمن، فهو لا يظهر إلا مرة واحدة:

{
  "id": "665f1b2c9a3e4d0012ab34cd",
  "url": "https://example.com/webhooks/taketheme",
  "events": ["order.placed", "order.paid", "order.fulfilled"],
  "isActive": true,
  "secret": "whsec_3a7f...c9d2"
}

2. استقبل وتحقّق

ينبغي لعنوانك التحقق من التوقيع قبل الوثوق بالحمولة:

import express from "express";
import crypto from "node:crypto";

const app = express();
const SIGNING_SECRET = process.env.TAKETHEME_WEBHOOK_SECRET; // whsec_...

// Capture the RAW body — signature is computed over the exact bytes sent.
app.post(
  "/webhooks/taketheme",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const header = req.get("X-TakeTheme-Signature");
    const rawBody = req.body; // Buffer

    if (!verifySignature(rawBody, header, SIGNING_SECRET)) {
      return res.status(400).send("Invalid signature");
    }

    const event = JSON.parse(rawBody.toString("utf8"));

    // Respond fast, then do the heavy lifting asynchronously.
    res.status(200).send("ok");

    switch (event.type) {
      case "order.paid":
        // fulfill(event.data.object)
        break;
      // ...
    }
  }
);

تجد التنفيذ الكامل لـ verifySignature (وإصداراته بلغات Python وPHP وRuby وGo) في التحقق من التواقيع.

مبادئ التصميم

• التسليم مرة واحدة على الأقل. قد يصل التسليم أكثر من مرة أحيانًا (مثلًا إذا تأخر خادمك في الرد فأعادت TakeTheme المحاولة). اجعل معالجك آمن التكرار بإسقاط المكرر اعتمادًا على id الحدث أو ترويسة X-TakeTheme-Delivery.
• لا ترتيب مضمون. تُسلَّم الأحداث فور وقوعها، لكن إعادة المحاولة عبر الشبكة قد تجعلها تصل بترتيب مختلف. اعتمد على حقول الحمولة (مثل paymentStatus) في التسوية بدل افتراض الترتيب.
• ردّ بسرعة. أكّد الاستلام بالرمز 2xx فورًا وأجّل العمل البطيء (الكتابة في قاعدة البيانات، استدعاء خدمات خارجية) إلى مهمة خلفية. وتعتبر TakeTheme أي رد يتجاوز 10 ثوانٍ فشلًا.
• تحقّق دائمًا. لا تتصرف بناءً على حمولة غير مُتحقَّق منها أبدًا — فمن يعرف رابطك يستطيع تزوير الأحداث.

الخطوات التالية

• مرجع الأحداث — كل حدث وحقول حمولته.
• التحقق من التواقيع — التأكد من الأصالة بلغتك.
• التسليم وإعادة المحاولة والإدارة — الترويسات وجدول إعادة المحاولة والسجلات وإدارة العناوين.