الفرق بين الـ API والـ Webhook: “لا تتصل بنا، نحن سنتصل بك”

عند بناء أي نظام أتمتة حديث، ستصادف غالباً خيارين متكررين لتبادل البيانات بين الأنظمة: API وWebhook. ورغم أن المصطلحين يُستخدمان أحياناً وكأنهما بديلان مباشرَان، فإن الحقيقة التقنية مختلفة تماماً. أحدهما يعتمد على أن تطلب أنت البيانات عند الحاجة، والآخر يعتمد على أن يرسل لك النظام الآخر إشعاراً فور وقوع الحدث.

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

ما هو API عملياً؟

الـ API هو واجهة تسمح لتطبيق بالاستفسار أو التفاعل مع تطبيق آخر من خلال طلبات منظمة. في النموذج التقليدي، يرسل العميل طلباً إلى Endpoint معين، ثم ينتظر استجابة تحتوي على بيانات أو نتيجة تنفيذ عملية ما.

هذا النمط يسمى غالباً Request/Response. أي أنك أنت من يبدأ الاتصال. ترسل طلب GET لجلب بيانات، أو POST لإنشاء مورد جديد، أو غير ذلك حسب تصميم الخدمة. ولتفصيل بنية الطلب، يفيد الرجوع إلى تشريح طلب الـ API: الـ Endpoint، الـ Headers، والـ Body.

متى يكون API هو الخيار الصحيح؟
عندما تحتاج إلى:

• جلب بيانات عند الطلب.
• تنفيذ عمليات مباشرة مثل إنشاء طالب أو تحديث طلب.
• البحث، التصفية، أو استعلامات مرنة.
• التحكم الكامل في توقيت الاتصال وعدد الطلبات.

ما هو Webhook؟

الـ Webhook هو آلية إشعار قائمة على الأحداث. بدلاً من أن تستمر في سؤال النظام: “هل حدث شيء جديد؟”، تقوم بتزويده بعنوان URL خاص بك، وعندما يقع حدث محدد، يرسل النظام طلباً إليك تلقائياً، غالباً باستخدام POST.

لهذا جاء الوصف الشهير: “لا تتصل بنا، نحن سنتصل بك”. هذه العبارة تلخص الفرق بالكامل. في الـ Webhook، أنت لا تستعلم باستمرار، بل تنتظر إشعاراً آنياً عندما يتغير شيء مهم، مثل تسجيل مستخدم جديد، إتمام دفعة، أو نجاح تسليم درس في منصة تعليمية.

الفرق الجوهري: Polling مقابل Push

الفرق الأهم بين الـ API والـ Webhook هو اتجاه بدء الاتصال. مع الـ API أنت تطلب. مع الـ Webhook الطرف الآخر يدفع إليك البيانات عند وقوع الحدث.

نمط API Polling

في هذا الأسلوب، تكتب سكربت يقوم كل دقيقة مثلاً بطلب بيانات جديدة من خدمة خارجية. هذا مفيد عندما لا توفر الخدمة Webhook، لكنه يستهلك طلبات أكثر وقد ينتج تأخيراً زمنياً بين وقوع الحدث واكتشافه.

نمط Webhook Push

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

مثال واقعي من الأتمتة التعليمية

لنفترض أنك تدير منصة دورات، وتريد إنشاء حساب طالب في نظام خارجي بعد كل عملية شراء. لديك خياران:

• استخدام API للتحقق كل 5 دقائق من الطلبات الجديدة.
• استخدام Webhook من المتجر ليتم إشعارك فور نجاح الدفع.

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

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

1. تنشئ Endpoint في خادمك يستقبل الطلبات.
2. تسجل هذا العنوان داخل النظام المرسل.
3. تحدد الأحداث المطلوبة مثل order.paid أو student.enrolled.
4. عند وقوع الحدث، يرسل النظام طلب HTTP إلى عنوانك.
5. تتحقق من التوقيع أو سرية الرسالة ثم تعالج Payload.
6. تعيد رمز حالة مناسب مثل 200 أو 202.

وإذا أردت فهماً أوضح لكيفية انتقال الطلبات عبر الشبكة، فراجع فهم بروتوكول HTTP: رحلة البيانات من جهازك إلى السيرفر، وكذلك شرح أفعال الـ HTTP (GET, POST, PUT, DELETE) والفرق بينها.

مثال برمجي: استقبال Webhook في Node.js

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/order-paid', async (req, res) => {
  try {
    const event = req.body;

    if (event.type === 'order.paid') {
      const orderId = event.data.orderId;
      const customerEmail = event.data.email;

      console.log('New paid order:', orderId, customerEmail);

      // هنا يمكنك استدعاء API خارجي لإنشاء مستخدم أو منحه صلاحية دورة
    }

    return res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook processing failed:', error.message);
    return res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Webhook listener running on port 3000');
});

مثال على Payload نموذجي

غالباً تصل بيانات الـ Webhook بصيغة JSON. وإذا لم تكن معتاداً على قراءتها، فمقال لغة الـ JSON: كيف تقرأ وتكتب البيانات التي تفهمها الآلات يساعدك كثيراً.

{
  "type": "order.paid",
  "createdAt": "2025-01-10T12:45:00Z",
  "data": {
    "orderId": "ORD-10025",
    "email": "student@example.com",
    "courseId": "course_987",
    "amount": 199
  }
}

توثيق نقطة الاستقبال:
POST /webhooks/order-paid
المهمة: استقبال إشعار نجاح الدفع.
نوع المحتوى: application/json
الاستجابة الناجحة: 200 OK
عند فشل المعالجة: سجل الخطأ داخلياً وأعد 500 فقط إذا كنت تريد من المرسل إعادة المحاولة.

مزايا وقيود كل خيار

مزايا API

• مرونة عالية في الاستعلام والتحكم.
• مناسب للعمليات التفاعلية ولوحات التحكم.
• يمكن استخدامه لجلب بيانات تاريخية أو مفلترة.

قيود API

• قد يحتاج إلى Polling مستمر لاكتشاف التغييرات.
• عدد طلبات أكبر واستهلاك أعلى للحصص Rate Limits.

مزايا Webhook

• استجابة شبه فورية للأحداث.
• تقليل الطلبات غير الضرورية.
• ممتاز لتدفقات الأتمتة المعتمدة على الأحداث.

قيود Webhook

• يتطلب خادماً عاماً قابلاً للوصول.
• يحتاج إلى تحقق أمني مثل التوقيع أو Secret Token.
• قد تصلك الأحداث مكررة، لذا يجب دعم Idempotency.

أفضل ممارسة احترافية: لا تفصل بينهما

الخطأ الشائع هو التفكير أن عليك اختيار واحد فقط. في الواقع، أقوى البنى تعتمد على الاثنين معاً. استخدم Webhook لاكتشاف الحدث فوراً، ثم استخدم API لجلب البيانات الكاملة أو تنفيذ تحديثات لاحقة.

هذا النمط يمنحك سرعة، ويقلل الاستهلاك، ويرفع موثوقية الأتمتة. كما أنه يساعدك على معالجة الأخطاء بذكاء عبر إعادة المحاولة، وتسجيل الأحداث، ومراجعة رموز الحالة (HTTP Status Codes): ماذا يخبرك السيرفر بـ 200 أو 404؟ لفهم استجابات الفشل والنجاح.

الخلاصة

إذا كان API يعني: “اذهب واسأل عندما تحتاج”، فإن Webhook يعني: “سأخبرك فور حدوث شيء”. الأول مثالي للاستعلامات والعمليات الموجهة، والثاني مثالي للأحداث الفورية. وفي البيئات الاحترافية، لا يعمل أحدهما ضد الآخر، بل يكمل أحدهما الآخر.

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