ما هو الويب هوك (Webhook) وكيف تستخدمه بأمان؟

الإجابة المختصرة على سؤال «ما هو الويب هوك؟»: عندما يقع حدث في نظام ما (تم تحصيل دفعة، تم تسليم طرد، تم إلغاء طلب)، يرسل ذلك النظام من تلقاء نفسه طلب HTTP إلى عنوان حددته أنت، دون أن تطلب منه ذلك. في الـ API العادي أنت من يطرح السؤال؛ أما مع الويب هوك فالخبر يأتيك. يبدو الفرق صغيرًا، لكنه يغيّر تكلفة التكامل وسرعته وسطح الهجوم فيه من البداية إلى النهاية. في هذا المقال نشرح كيف يعمل الويب هوك، وأين يُستخدم، وما الذي يجب أن يفعله المستقبِل المبني بشكل صحيح، وما الذي يجب أن تصممه مسبقًا إذا كان نظامك سيرسل ويب هوك إلى الآخرين. هذه هي القواعد التي نتبعها عند بناء طبقة التكامل في مشاريع البرمجيات الخاصة.

ما الفرق بين الويب هوك والـ API؟

كلاهما يتواصل عبر HTTP؛ الفرق في الاتجاه والتوقيت. مع الـ API أنت العميل: تسأل «هل دُفع هذا الطلب؟» فيخبرك الطرف الآخر بالحالة الراهنة. ولمعرفة الجواب إما أن يضغط المستخدم زرًا أو يطرح نظامك السؤال نفسه على فترات منتظمة؛ وهذا ما يسمى الاستطلاع الدوري (polling). أما مع الويب هوك فأنت تعطي عنوانًا («أخبرني هنا عندما تصل دفعة»)، وعندما يقع الحدث يرسل النظام الآخر طلب POST إلى ذلك العنوان. أنت لا تسأل، بل تستمع. شرحنا المفاهيم العامة في مقال ما هو تكامل الـ API؛ هذا المقال يتناول جانب الويب هوك فقط.

الاستطلاع الدوري والويب هوك ليسا متنافسين بل متكاملان. عندما تكون الأحداث متكررة والاستجابة الفورية مهمة (تأكيد الدفع، وصول رسالة)، فالويب هوك هو الأداة الصحيحة: النظام الذي يسأل «هل وصل؟» كل خمس ثوانٍ يهدر الطلبات ويتأخر مع ذلك ثانيتين ونصفًا في المتوسط. وعندما تكون الأحداث نادرة ولا يوفر الطرف الآخر ويب هوك، يبقى الاستطلاع الدوري الخيار الوحيد؛ وهذا حال معظم برامج المحاسبة، وقد تناولناه في مقال تكامل برنامج المحاسبة.

كيف يعمل الويب هوك خطوة بخطوة؟

• تفتح في نظامك عنوان HTTPS عامًا، مثل /api/webhooks/payment. يقبل هذا العنوان طلبات POST فقط ولا ينتظر أي جلسة مستخدم.
• تسجّل هذا العنوان في لوحة مزود الخدمة أو عبر واجهته البرمجية؛ فيعطيك المزود مفتاحًا سريًا (secret).
• عند وقوع الحدث يرسل المزود نوع الحدث وبياناته بصيغة JSON إلى هذا العنوان، ويضع في ترويسة الطلب توقيعًا مولّدًا بالمفتاح السري.
• يتحقق خادمك من التوقيع، ويسجّل الحدث، ويعيد للمزود الرمز 200 بسرعة، ثم ينفّذ العمل الفعلي (تعليم الطلب كمدفوع، إرسال بريد) بشكل منفصل.
• إذا لم يعد خادمك 200 أو أعاده متأخرًا، يعيد المزود إرسال الحدث نفسه على فترات متزايدة؛ ولهذا قد يصل الحدث الواحد أكثر من مرة.

أين يُستخدم الويب هوك؟

في المشاريع المؤسسية التي نعمل عليها، يظهر الويب هوك غالبًا في تكاملات الدفع والشحن والمتاجر الإلكترونية والمراسلة. في تكامل الدفع ما يعلّم الطلب كمدفوع ليس شاشة النجاح التي يراها المستخدم بل الويب هوك المتحقق منه القادم من المزود. وفي تكامل الشحن تخبرك شركة الشحن بكل تغيير في حالة التسليم (قيد التوصيل، تم التسليم، مرتجع) فتتحدث صفحة التتبع لديك دون سؤال. وفي تكامل المتاجر الإلكترونية تصل الطلبات الجديدة والإلغاءات بهذه الطريقة، ومع WhatsApp Business API تصل الرسائل الواردة وتقارير التسليم كذلك. القاسم المشترك: الحدث يقع خارج نظامك، في نظام شخص آخر، وأنت لا تتحكم في توقيته.

القاعدة الأولى للويب هوك: الويب هوك إشعار وليس مصدر الحقيقة. هل حُصّل المال فعلًا؟ هل أُلغي الطلب فعلًا؟ عند الشك، طريقة التحقق هي الاستعلام من واجهة المزود البرمجية بمعرّف الحدث. المستقبِل الجيد يثق بالويب هوك لكنه لا يعتمد عليه وحده أبدًا.

أمان الويب هوك: التحقق من التوقيع والتسليمات المكررة

عنوان الويب هوك عام بحكم تعريفه؛ وكل من يعرفه يستطيع إرسال طلب مزيف يقول «تم استلام الدفعة». لذلك يوقّع كل مزود الطلب بالمفتاح السري، وتعيد أنت حساب التوقيع على جسم الطلب الخام وتقارنه. هناك خطآن كلاسيكيان: تحويل الجسم إلى JSON أولًا ثم توقيع الناتج (تتغير المسافات وترتيب الحقول فلا يتطابق التوقيع أبدًا)، والمقارنة بالمساواة البسيطة (معرّضة لهجمات التوقيت). الموضوع الكبير الثاني هو التسليمات المكررة: إذا لم يحصل المزود على 200 فإنه يعيد إرسال الحدث نفسه؛ وما لم يكن منطق عملك فريدًا لكل معرّف حدث، يُخصم المخزون مرتين أو يُرسل بريدان للطلب نفسه. معالج المسار في Next.js أدناه يطبّق القواعد الثلاث معًا: مقارنة التوقيع بزمن ثابت على الجسم الخام، والتفرد بمعرّف الحدث، ونقل العمل الثقيل إلى طابور ليحصل المزود على رد سريع.

// app/api/webhooks/payment/route.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  // The signature is computed over the RAW body; do not JSON.parse first.
  const raw = await req.text();
  const received = req.headers.get('x-signature') ?? '';
  const expected = createHmac('sha256', process.env.PAYMENT_WEBHOOK_SECRET!)
    .update(raw)
    .digest('hex');

  // Constant-time comparison: prevents timing attacks.
  if (
    received.length !== expected.length ||
    !timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  ) {
    return new NextResponse('invalid signature', { status: 401 });
  }

  const event = JSON.parse(raw) as { id: string; type: string; data: unknown };

  // Idempotency: if the same event arrives again, business logic does not rerun.
  const isNew = await db.webhookEvents.insertIfAbsent({
    id: event.id,
    type: event.type,
    payload: raw,
    receivedAt: new Date(),
  });
  if (!isNew) return NextResponse.json({ ok: true, duplicate: true });

  // Heavy work (stock, email, invoice) goes to a queue; fast 200 to the provider.
  await queue.enqueue('process-webhook', { eventId: event.id });
  return NextResponse.json({ ok: true });
}

حفظ الحدث الخام ليس ترفًا تنظيميًا. عندما تفشل المهمة في الطابور يمكنك إعادة معالجة السجل؛ وعندما تختلف مع المزود حول ما إذا كان الحدث قد سُلّم يكون لديك دليل؛ وعندما تبدأ بدعم حقل جديد يمكنك إعادة قراءة الأحداث السابقة. شرحنا إعداد الطابور وتتبع الأخطاء في مقال مراقبة الأخطاء والتسجيل؛ ومستقبِل الويب هوك هو أفضل مثال على «إنذار الصمت» الوارد هناك، لأن الويب هوك الذي يتوقف عن الوصول لا ينتج خطأ، بل يصمت فحسب.

ماذا لو لم يصل الويب هوك أبدًا؟ إعادة المحاولة والتعويض

إذا توقف خادمك لساعة فإن أحداث تلك الساعة لا تضيع، لكن مدة إعادة المحاولة تختلف باختلاف المزود: بعضهم يعيد المحاولة لساعات، وبعضهم لثلاثة أيام، وبعضهم يعطّل العنوان كليًا بعد خمس محاولات فاشلة. لذلك يُعدّ أمران منذ اليوم الأول. الأول: تُكتب سياسة إعادة المحاولة لدى المزود وشرط تعطيل العنوان في وثيقة التسليم. الثاني: مهمة مطابقة دورية: مرة كل ليلة تُسحب قائمة أحداث أو عمليات آخر 24 ساعة من المزود، وتُقارن بسجلاتك، وتُعالج الفجوات. الويب هوك هو المسار الفوري، والمطابقة هي حزام الأمان؛ والتكامل الذي لا يُبنى بكليهما سيفقد البيانات يومًا ما بصمت.

إذا كان نظامك سيرسل الويب هوك

إذا كنت تبني بوابة موزعين أو منتج SaaS أو لوحة مؤسسية، فسيقول لك عميل يومًا ما: «أخبروا نظامنا عند إنشاء طلب». في ذلك اليوم عليك أن توفر كل ما كنت تتوقعه من المستقبِل: الأحداث تحمل معرّفًا فريدًا وختمًا زمنيًا؛ كل طلب موقّع بمفتاح سري خاص بكل عميل؛ الإرسال يتم من طابور وتُعاد محاولة التسليمات الفاشلة على فترات متزايدة (دقيقة، 5 دقائق، 30 دقيقة، ساعتان)؛ وفي لوحة العميل سجل تسليم وزر «إعادة الإرسال». أكثر ما يُغفل هو إصدارات الأحداث: إضافة حقل جديد إلى الجسم مقبولة، أما إعادة تسمية حقل قائم أو تغيير معناه فتكسر تكاملات عملائك؛ لذا فإن مخطط الحدث جزء من العقد. لتصميم واجهة برمجية عامة راجع مقال REST أم GraphQL، ولسطح الهجوم العام راجع مقال أمان الموقع الإلكتروني.

خمسة أخطاء تفسد مشروع الويب هوك

• عدم التحقق من التوقيع أو قول «سنضيفه لاحقًا»: العنوان عام، فيعمل موقّعًا منذ اليوم الأول.
• تنفيذ العمل الفعلي داخل طلب الويب هوك: عندما يبطؤ خادم البريد تنتهي مهلة المزود، فيعيد الإرسال، ويُنفَّذ العمل مرتين.
• عدم حفظ معرّف الحدث: لا يمكن تمييز التسليم المكرر، فيُعالج الطلب نفسه مرتين.
• توجيه الويب هوك الحي للمزود إلى بيئة اختبار: مفاتيح الاختبار والإنتاج منفصلة، ويجب أن تكون العناوين منفصلة أيضًا.
• اعتبار الويب هوك مصدر الحقيقة الوحيد: بلا مهمة مطابقة لا يُكتشف الانقطاع إلا عندما يتصل العميل.

الخلاصة

الويب هوك هو أسرع وأرخص طريقة لربط نظامين؛ وما يسبب المشاكل ليس الويب هوك بل المستقبِل الناقص. التحقق من التوقيع، والتفرد بمعرّف الحدث، والطابور، ومهمة المطابقة: متى اكتملت هذه الأجزاء الأربعة، يعمل تكاملك مع الدفع أو الشحن أو المتجر الإلكتروني أو المراسلة بهدوء لسنوات. إذا كنت تخطط لمشروع يتضمن طبقة تكامل، فاطّلع على خدمة البرمجيات الخاصة لدينا أو اطلب عرض سعر؛ وفي مرحلة الاستكشاف نحدد معًا أي المزودين يوفر ويب هوك وأين سيتعين عليك الاكتفاء بالاستطلاع الدوري والمطابقة.