مقدمة

إذا سبق لك إعداد تكامل بين خدمتين — مثلًا لجعل بيانات من نظام ما تصل تلقائيًا إلى نظام إدارة علاقات العملاء (CRM) أو إلى جدول بيانات في Google Sheets — فمن المرجح أنك صادفت مصطلح "ويب هوك" (webhook). إنها واحدة من تلك التقنيات التي تدعم بصمت جزءًا كبيرًا من الأتمتة الحديثة، من إشعارات Slack إلى مزامنة الطلبات في متجر إلكتروني. في هذا المقال، سنشرح ما هي الويب هوك بعبارات بسيطة، وكيف تختلف عن طلبات API العادية، وكيفية إعداد إشعارات النقرات للروابط المختصرة عمليًا باستخدام ميزة الويب هوك في Lix.li.

ما هي الويب هوك ببساطة

الويب هوك هي طريقة لنقل البيانات تلقائيًا من خدمة إلى أخرى في اللحظة التي يحدث فيها حدث معيّن. فبدلًا من أن يسأل نظامك باستمرار "هل ظهر شيء جديد؟"، ترسل الخدمة نفسها البيانات إلى خادمك بمجرد وقوع الحدث. أسهل طريقة لفهم الفرق هي عبر تشبيه البريد:

طلب API العادي أشبه بأن تذهب بنفسك بشكل متكرر إلى صندوق البريد للتحقق مما إذا وصلت رسالة أم لا.
الويب هوك أشبه بالاشتراك في خدمة توصيل: تصلك الرسالة إلى باب منزلك تلقائيًا بمجرد أن تكون جاهزة. من الناحية التقنية، الويب هوك هو ببساطة طلب HTTP عادي (غالبًا POST) يرسله خادم إلى عنوان URL محدد مسبقًا على خادم آخر عند حدوث الحدث المعني — مثل دفع طلب، أو تغيير حالة مهمة، أو في حالة Lix.li، النقر على رابط مختصر.

لماذا نحتاج إلى الويب هوك

تحل الويب هوك مشكلة محددة تمامًا: كيفية الحصول على بيانات محدّثة دون الحاجة إلى استعلام خدمة خارجية باستمرار (polling). بدون الويب هوك، لمعرفة الأحداث الجديدة، سيتعين عليك إرسال طلبات دورية إلى واجهة API — كل دقيقة، أو كل خمس دقائق — والتحقق في كل مرة مما إذا كان هناك شيء جديد. هذا يخلق حملًا إضافيًا غير ضروري على كلا الخادمين، ويضيف دائمًا تأخيرًا بين وقوع الحدث فعليًا واللحظة التي تعلم فيها بحدوثه. تقلب الويب هوك هذا المنطق رأسًا على عقب: الخدمة تُخطرك بنفسها عند حدوث شيء ما. وهذا مفيد بشكل خاص لـ:

أتمتة العمليات التجارية — مثل تسجيل العملاء المحتملين الجدد تلقائيًا في نظام إدارة علاقات العملاء.
التكامل مع أدوات التحليل — نقل بيانات النقرات إلى نظام التتبع الخاص بك.
الروبوتات والإشعارات — إرسال الأحداث إلى بوت على Telegram أو قناة Slack الخاصة بالفريق.
مزامنة البيانات — تحديث جداول Google Sheets، أو لوحات المعلومات، أو الأنظمة الداخلية في الوقت الفعلي.

كيف تعمل الويب هوك: مثال Lix.li

في Lix.li، تتيح لك الويب هوك استقبال بيانات النقرات على روابطك المختصرة مباشرة على خادمك الخاص — تلقائيًا، دون الحاجة لاستعلام واجهة API الخاصة بالخدمة باستمرار. هذا مفيد إذا كنت تريد إدخال هذه الأحداث في نظام إدارة علاقات العملاء الخاص بك، أو نظام تحليلات، أو Google Sheets، أو بوت Telegram، أو أي نظام أتمتة آخر.

كيف تم بناء هذا النظام

لا يتم إرسال النقرات واحدة تلو الأخرى، بل يتم تجميعها وتسليمها على شكل دفعات، مرة كل بضع دقائق. هذا يقلل من الحمل على خادمك وعلى خادم Lix.li على حد سواء.
يحدث التسليم بالقرب من الوقت الفعلي، لكن ليس بشكل فوري — فالويب هوك مصممة لسيناريوهات يكون فيها تأخير بضع دقائق مقبولًا، وليس لرد فعل فوري على كل نقرة بمفردها.
يعتمد ضمان التسليم على مبدأ "مرة واحدة على الأقل": إذا حدث عطل في الشبكة أثناء الإرسال، قد تصل الدفعة مرة أخرى. لهذا السبب، لكل حدث معرّف فريد event_id — يجب عليك استخدامه لتصفية التكرارات من جانبك.

إعداد ويب هوك في لوحة التحكم

ميزة الويب هوك متاحة في باقة Premium. يستغرق الإعداد بضع خطوات فقط:

افتح قسم "الويب هوك" في لوحة التحكم الخاصة بك وانقر على "إضافة".
حدد ما يلي:
- رابط الاستقبال (URL) — العنوان على خادمك الذي سيستقبل الطلبات الواردة (مثل https://api.موقعك.com/webhooks/lix)؛
- نطاق التطبيق — هل يتم إرسال الأحداث لجميع الروابط، أم لمجموعة روابط محددة، أم لرابط واحد فقط؛
- ما إذا كان يجب تضمين عنوان IP الخاص بالزائر في بيانات الحدث (معطّل افتراضيًا لأنها بيانات شخصية).
مباشرة بعد إنشاء الويب هوك، ستظهر لك مفتاح سري (secret) يُعرض مرة واحدة فقط — احرص على حفظه، إذ يُستخدم للتحقق من صحة الطلبات الواردة.
انقر على "اختبار" — سترسل الخدمة حدثًا تجريبيًا وتُظهر ما إذا كان خادمك قد استجاب بشكل صحيح.

ما الذي يصل إلى خادمك

يُرسل كل طلب باستخدام طريقة POST مع نص بصيغة application/json. إلى جانب البيانات نفسها، يتضمن الطلب بعض الترويسات الوظيفية:

الترويسة	الغرض
`X-Lix-Signature`	توقيع نص الطلب بصيغة `sha256=` — يُستخدم للتحقق من صحته.
`X-Lix-Timestamp`	وقت إرسال الطلب، بصيغة طابع زمني Unix.
`X-Lix-Delivery`	معرّف فريد لعملية التسليم.
`User-Agent`	بقيمة `Lix-Webhooks/1.0`.
يحتوي نص الطلب على دفعة الأحداث نفسها:

{
  "delivery_id": "0f3b9c2e-6a1d-4e88-9d5a-2f8c1b7a4e10",
  "event_type": "redirects.batch",
  "sent_at": "2026-06-01T12:05:00Z",
  "window": {
    "from": "2026-06-01T12:00:00Z",
    "to":   "2026-06-01T12:03:30Z"
  },
  "count": 2,
  "truncated": false,
  "events": [
    {
      "event_id":   "2ef7bde608ce5404e97d5f042f95f89f1c232871",
      "link_id":    12345,
      "datetime":   "2026-06-01T12:01:00Z",
      "country":    "US",
      "city":       "Boston",
      "browser":    "Chrome",
      "os":         "Windows",
      "device":     "Desktop",
      "ref_domain": "google.com",
      "group_id":   null,
      "is_bot":     false
    }
  ]
}

يتضمن كل حدث ضمن الدفعة معرّف الرابط، ووقت النقرة بتوقيت UTC، والبلد، والمدينة، والمتصفح، ونظام التشغيل، ونوع الجهاز، والنطاق الذي جاءت منه النقرة، ومعرّف المجموعة (إن وُجد)، وعلامة تشير إلى ما إذا كانت النقرة صادرة عن روبوت. لا يُدرج عنوان IP الخاص بالزائر إلا إذا فعّلت هذا الخيار صراحةً عند إعداد الويب هوك. إذا تراكم عدد كبير جدًا من الأحداث، قد تُوسم الدفعة بـ truncated: true — وهذا يعني أن جزءًا من البيانات سيصل مع عملية التسليم التالية، دون فقدان أي بيانات.

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

بما أن عنوان URL الخاص بخادمك يمكن تقنيًا أن يستقبل طلبًا من أي مكان، من المهم التأكد من أن الطلب جاء فعلًا من Lix.li وليس مزيفًا. وهذا هو الغرض من التوقيع الموجود في ترويسة X-Lix-Signature. مبدأ التحقق: تأخذ نص الطلب "الخام" (غير المعالج)، وتحسب منه قيمة HMAC-SHA256 باستخدام مفتاحك السري، ثم تقارن النتيجة بما ورد في الترويسة. يجب أن تتم المقارنة بطريقة آمنة (زمن ثابت) لتفادي هجمات توقيت المقارنة. مثال بلغة PHP:

$raw    = file_get_contents('php://input');
$secret = 'your_secret';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_LIX_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

مثال بلغة Node.js (Express):

const crypto = require('crypto');
// من المهم الحصول على النص الخام: app.use(express.raw({ type: 'application/json' }))
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const got = req.header('X-Lix-Signature') || '';
if (expected.length !== got.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
  return res.sendStatus(401);
}

مثال بلغة Python (Flask):

import hmac, hashlib
raw = request.get_data()  # البايتات الخام
expected = 'sha256=' + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Lix-Signature', '')):
    return '', 401

متطلبات خادمك المستقبِل

لكي تعمل الويب هوك بشكل مستقر، يجب أن يستوفي خادمك بعض القواعد:

الاستجابة برمز 2xx. أي رمز آخر، أو انتهاء مهلة الانتظار، يُعتبر فشلًا، وستُعاد محاولة التسليم.
الاستجابة بسرعة. لديك بضع ثوانٍ فقط للرد — تجنّب معالجة البيانات بشكل متزامن داخل معالج الطلب نفسه. النهج الصحيح هو: حفظ البيانات الواردة بسرعة (في قائمة انتظار أو قاعدة بيانات مثلًا)، وإرجاع 2xx، ثم معالجتها بشكل منفصل لاحقًا.
إزالة التكرار بناءً على event_id. بسبب آلية إعادة المحاولة، قد يصل الحدث نفسه أحيانًا مرتين.
أن يكون التعامل معزّزًا (idempotent). يجب ألا تؤدي إعادة معالجة الدفعة نفسها إلى إفساد بياناتك.
التحقق دائمًا من التوقيع في كل طلب وارد.
استخدام HTTPS. لا يُدعم استخدام عناوين محلية أو داخلية لاستقبال الويب هوك.

ماذا يحدث عند حدوث أعطال

إذا لم يستجب خادمك برمز 2xx، تعيد Lix.li محاولة التسليم مع زيادة الفاصل الزمني تدريجيًا بين المحاولات. إذا لم يستجب الخادم المستقبِل إطلاقًا لفترة طويلة (عدة محاولات فاشلة متتالية)، تُوقَف الويب هوك تلقائيًا لتجنب إرسال البيانات إلى فراغ. يظهر هذا في سجل عمليات التسليم في لوحة التحكم الخاصة بك، وبمجرد إصلاح المشكلة من جانبك، يمكنك إعادة تفعيل الويب هوك.

إدارة الويب هوك في لوحة التحكم

تتوفر الإجراءات التالية لكل ويب هوك مُعدّ:

اختبار — إرسال حدث تجريبي واحد ورؤية النتيجة فورًا: النجاح، أو رمز الاستجابة المحدد من خادمك.
إيقاف مؤقت / استئناف — إيقاف أو استئناف تسليم الأحداث مؤقتًا.
تدوير المفتاح السري — إنشاء مفتاح جديد ليحل محل القديم؛ يتوقف المفتاح القديم عن العمل فورًا، لذا احرص على تحديثه في جانبك أيضًا على الفور.
حذف — إزالة الويب هوك بالكامل.
سجل عمليات التسليم — سجل بأحدث عمليات التسليم، يوضح الحالة، ورمز استجابة HTTP، وعدد الأحداث في الدفعة، ووقت الإرسال.

أسئلة شائعة

ما مدى سرعة وصول الأحداث؟ على شكل دفعات، تقريبًا كل بضع دقائق، مع تأخير بسيط للمعالجة. هذا ليس تسليمًا فوريًا (push)، بل سيناريو قريب من الوقت الفعلي. هل يمكن أن يصل الحدث نفسه مرتين؟ نعم، عند إعادة محاولة التسليم بعد عطل في الشبكة. لهذا السبب بالضبط، من المهم إزالة تكرار الأحداث بناءً على حقل event_id من جانبك. هل الترتيب الصارم للأحداث مضمون؟ ضمن الدفعة الواحدة، تأتي الأحداث بترتيب زمني، لكن لا يوجد ضمان صارم للترتيب بين الدفعات المختلفة — استخدم حقل datetime الخاص بكل حدث للترتيب. ماذا يحدث مع حجم ترافيك كبير جدًا؟ إذا تراكم عدد كبير جدًا من الأحداث خلال فترة واحدة، تُوسم الدفعة بـ truncated: true، ويصل الجزء المتبقي من البيانات مع عملية التسليم التالية — دون فقدان أي بيانات في هذه العملية. هل استخدام HTTPS إلزامي؟ نعم، يجب أن يبدأ عنوان المستقبِل بـ https://. لا تُقبل العناوين المحلية أو الداخلية. هل يمكنني استقبال الأحداث لرابط واحد أو مجموعة روابط فقط؟ نعم — عند إنشاء ويب هوك، يمكنك اختيار نطاق "رابط واحد" أو "مجموعة" بدلًا من جميع روابط الحساب.