DEV Community

Cover image for الفرق بين الويب هوك و API: ما هو الفرق الحقيقي؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

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

"الويب هوك مقابل واجهة برمجة التطبيقات" (Webhook vs API) ليس سؤالًا عن تقنيتين متنافستين بقدر ما هو سؤال عن اتجاه الاتصال. إذا سبق وربطت Stripe أو GitHub بتطبيقك، فالفكرة الأساسية هي: واجهة برمجة التطبيقات العادية تجعلك تطلب البيانات، أما الويب هوك فيجعل المزود يرسل الحدث إلى خادمك عند حدوثه.

جرّب Apidog اليوم

في هذا الدليل ستعرف الفرق العملي بينهما، متى تستخدم كل نمط، وكيف تصمم نقطة نهاية Webhook قابلة للاختبار. إذا كنت تبني أو تختبر تكاملات، فإن Apidog يساعدك على تصميم واختبار واجهات REST ومستقبلات الويب هوك في مساحة عمل واحدة.

الإجابة المختصرة

  • واجهة برمجة التطبيقات العادية، غالبًا REST، تعمل بنمط طلب-استجابة. تطبيقك يرسل طلبًا، والمزود يعيد استجابة. أنت تتحكم في التوقيت.
  • الويب هوك يعمل بنمط دفع الأحداث. المزود يرسل طلب HTTP إلى خادمك عندما يحدث حدث معين. المزود يتحكم في التوقيت.
  • كلاهما يستخدم HTTP غالبًا، وكلاهما يرسل JSON في حالات كثيرة. لذلك يُسمى الويب هوك أحيانًا "واجهة برمجة تطبيقات عكسية" أو "Push API".

الخلاصة العملية: ليست المسألة "Webhook ضد API"، بل Pull ضد Push.

ماذا يقصد المطورون بـ API؟

عندما يقول أحدهم "استدعِ الـ API"، فعادة يقصد REST API:

GET /orders/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

ثم تحصل على استجابة:

{
  "id": "123",
  "status": "paid",
  "total": 49.99
}
Enter fullscreen mode Exit fullscreen mode

هذا هو نموذج السحب Pull. لا يحدث شيء حتى ترسل الطلب.

استخدم هذا النمط عندما تحتاج إلى:

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

العيب: إذا أردت معرفة التغييرات فور حدوثها، ستحتاج إلى الاستقصاء Polling، مثل استدعاء endpoint كل 10 ثوانٍ. هذا يستهلك موارد وقد يضيف تأخيرًا. لمراجعة بنية الطلب والاستجابة، راجع فهم هيكل طلب واجهة برمجة التطبيقات (API).

ما هو الويب هوك؟

الويب هوك هو HTTP callback. أنت تسجل عنوان URL لدى المزود، مثل:

https://yourapp.com/webhooks/stripe
Enter fullscreen mode Exit fullscreen mode

وعندما يحدث حدث عند المزود، يرسل إليك طلبًا:

POST /webhooks/stripe HTTP/1.1
Host: yourapp.com
Content-Type: application/json
Stripe-Signature: t=...,v1=...

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "status": "succeeded"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

هنا تطبيقك لا يستدعي المزود. المزود هو من يستدعي تطبيقك.

هذا هو نموذج الدفع Push. يستخدمه Stripe لإعلامك بنجاح الدفع، ويستخدمه GitHub لإعلامك بحدوث push، وتستخدمه Slack لتشغيل أوامر وتكاملات.

للتعمق في جانب الاستقبال، راجع ما هو الويب هوك API.

Webhook مقابل API: الفرق الجوهري

البند واجهة API عادية REST Webhook
من يبدأ الاتصال أنت، كعميل المزود
النموذج طلب-استجابة Pull أحداث Push
التوقيت عندما ترسل الطلب عند وقوع الحدث
الاتجاه تطبيقك يستدعي المزود المزود يستدعي endpoint عندك
الأفضل لـ البيانات والإجراءات عند الطلب الأحداث غير المتوقعة
التكلفة الرئيسية قد تحتاج إلى Polling تحتاج إلى endpoint عام وآمن

أهم صف هو الأول: من يبدأ الاتصال؟

كل الفروق الأخرى تأتي من هذا الاتجاه.

هل الويب هوك مجرد API؟

نعم ولا.

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

  • HTTP
  • URL
  • Headers
  • JSON body
  • Status codes

لكن الفرق أن المزود يعمل كـ client، ونقطة النهاية عندك تعمل كـ server.

لذلك الصياغة الأدق هي: الويب هوك نمط اتصال داخل عالم APIs، وليس تقنية منفصلة تمامًا.

حتى OpenAPI 3.1 يدعم وصف الويب هوكس عبر حقل webhooks. ويمكن توثيقها واختبارها مثل أي عقد API آخر. للمزيد، راجع ردود نداء OpenAPI والويب هوكس.

متى تستخدم API عادية؟

استخدم REST API أو نمط طلب-استجابة عندما تكون أنت من يتحكم في التوقيت.

أمثلة:

  • المستخدم فتح صفحة الطلبات، فتجلب الطلبات الآن.
  • تريد إنشاء دفعة جديدة.
  • تريد تحديث ملف مستخدم.
  • تريد تشغيل تقرير عند ضغط زر.

مثال بسيط في Node.js:

const response = await fetch("https://api.example.com/orders/123", {
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`
  }
});

const order = await response.json();
console.log(order.status);
Enter fullscreen mode Exit fullscreen mode

هذا مناسب لأن التطبيق هو من قرر متى يحتاج البيانات.

متى تستخدم Webhook؟

استخدم Webhook عندما تريد التفاعل مع حدث لا تتحكم في توقيته.

أمثلة:

  • الدفع نجح أو فشل.
  • GitHub repo استقبل push.
  • ملف انتهت معالجته.
  • build اكتمل.
  • مستخدم ألغى اشتراكه.

بدلًا من هذا:

setInterval(async () => {
  const status = await checkPaymentStatus(paymentId);
  if (status === "paid") {
    fulfillOrder();
  }
}, 10000);
Enter fullscreen mode Exit fullscreen mode

استخدم Webhook يستقبل الحدث عند حدوثه:

app.post("/webhooks/payment", express.json(), async (req, res) => {
  const event = req.body;

  if (event.type === "payment_succeeded") {
    await fulfillOrder(event.data.orderId);
  }

  res.sendStatus(200);
});
Enter fullscreen mode Exit fullscreen mode

إذا كان الخيار الحقيقي هو Webhook أو Polling، فراجع الويب هوكس مقابل الاستقصاء (Polling).

كيف يعملان معًا في تكامل حقيقي؟

في التطبيقات العملية، غالبًا لا تختار واحدًا فقط. تستخدم الاثنين.

مثال Stripe:

  1. تطبيقك يستدعي Stripe API لإنشاء Payment Intent.
  2. Stripe يعالج الدفع.
  3. Stripe يرسل Webhook إلى تطبيقك عند نجاح أو فشل الدفع.
  4. تطبيقك يحدث الطلب داخليًا بناءً على الحدث.

أي أنك تستخدم:

  • API لبدء الإجراء.
  • Webhook لمعرفة النتيجة.

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

Webhooks مقابل WebSockets مقابل Polling

هذه المصطلحات قد تتداخل، لكن الفرق العملي واضح:

  • Polling: تطبيقك يسأل المزود مرارًا: "هل حدث شيء؟"
  • Webhook: المزود يخبر تطبيقك عندما يحدث شيء.
  • WebSocket: اتصال مستمر ثنائي الاتجاه مناسب للتدفقات الحية.

مقارنة سريعة:

النمط الاستخدام المناسب
Polling عندما لا يدعم المزود Webhooks أو عندما لا تحتاج إلى زمن حقيقي
Webhook أحداث منفصلة وغير متوقعة مثل الدفع أو push أو اكتمال مهمة
WebSocket تحديثات مستمرة مثل الدردشة أو الأسعار اللحظية أو collaboration

تفصيل إضافي هنا: الويب هوك مقابل الويب سوكيت.

كيفية بناء مستقبل Webhook بسيط

مثال باستخدام Express:

import express from "express";

const app = express();

app.use(express.json());

app.post("/webhooks/orders", async (req, res) => {
  const event = req.body;

  try {
    switch (event.type) {
      case "order.created":
        await handleOrderCreated(event.data);
        break;

      case "order.cancelled":
        await handleOrderCancelled(event.data);
        break;

      default:
        console.log(`Unhandled event type: ${event.type}`);
    }

    res.sendStatus(200);
  } catch (error) {
    console.error(error);

    // غالبًا سيعيد المزود المحاولة عند استجابة 5xx
    res.sendStatus(500);
  }
});

app.listen(3000, () => {
  console.log("Webhook receiver listening on port 3000");
});
Enter fullscreen mode Exit fullscreen mode

نقاط مهمة أثناء التنفيذ:

  • اجعل endpoint متاحًا عبر HTTPS.
  • أعد 2xx فقط بعد معالجة الحدث أو حفظه بأمان.
  • تعامل مع تكرار نفس الحدث، لأن المزود قد يعيد الإرسال.
  • تحقق من توقيع الطلب قبل الوثوق بالحمولة.
  • سجّل event id لتجنب المعالجة المكررة.

تحقق من توقيع Webhook

لا تثق بأي POST يصل إلى endpoint عام. يجب أن تتأكد أن الطلب قادم من المزود الحقيقي.

الفكرة العامة:

import crypto from "crypto";

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Enter fullscreen mode Exit fullscreen mode

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

كيفية تصميم واختبار API وWebhook باستخدام Apidog

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

يمكنك استخدام Apidog لتنظيم العمل كالتالي:

  1. صمم REST endpoints الخاصة بك.
  2. أضف أمثلة request وresponse.
  3. اختبر endpoints باستخدام assertions وسيناريوهات.
  4. أنشئ طلب POST يمثل حدث Webhook.
  5. أرسله إلى مستقبل الويب هوك لديك.
  6. وثّق الـ Webhooks بجانب REST APIs حتى يرى المستهلكون العقد الكامل.

مثال payload لاختبار مستقبل Webhook:

{
  "id": "evt_123",
  "type": "payment_succeeded",
  "created": 1710000000,
  "data": {
    "paymentId": "pay_456",
    "orderId": "ord_789",
    "amount": 4999,
    "currency": "USD"
  }
}
Enter fullscreen mode Exit fullscreen mode

بهذا تتعامل مع الويب هوك كعقد API قابل للتصميم والاختبار، وليس كجزء غامض يظهر فقط في الإنتاج.

يمكنك تنزيل Apidog لبناء واختبار REST APIs وWebhooks في مكان واحد.

الأسئلة الشائعة

هل الويب هوك هو API؟

الويب هوك نمط اتصال ضمن APIs. يستخدم HTTP وURL وHeaders وJSON، لكن الاتجاه معكوس: المزود يستدعي endpoint عندك بدلًا من أن تستدعي أنت endpoint عند المزود.

هل يمكن استخدام Webhook بدون API؟

ممكن، لكنه ليس النمط الأكثر شيوعًا. غالبًا تستدعي API لبدء إجراء، ثم تستقبل Webhook لمعرفة النتيجة. راجع ما هو الويب هوك API.

هل Webhook أسرع من API؟

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

هل تحل Webhooks محل REST APIs؟

لا. REST مناسب للطلبات والإجراءات التي تبدأها أنت. Webhooks مناسبة لإشعارات الأحداث التي يبدأها المزود. معظم الأنظمة تستخدم الاثنين.

هل الويب هوك آمن؟

يمكن أن يكون آمنًا إذا تحققت من التوقيع، استخدمت HTTPS، تعاملت مع إعادة الإرسال، ولم تثق بالحمولة بدون تحقق. ابدأ بقراءة التحقق من توقيع الويب هوك.

الخلاصة

إطار "Webhook مقابل API" مضلل قليلًا. الفرق الحقيقي هو اتجاه الاتصال:

  • API عادية: تطبيقك يطلب البيانات أو ينفذ إجراء.
  • Webhook: المزود يدفع حدثًا إلى تطبيقك عند حدوثه.

استخدم API عندما تتحكم أنت في التوقيت. واستخدم Webhook عندما يتحكم المزود في التوقيت. وفي أغلب التكاملات الإنتاجية، ستحتاج إلى الاثنين معًا.

عندما تكون مستعدًا للبناء، صمم APIs ونقاط Webhook واختبرها في Apidog.

Top comments (0)