ما هو Webhook؟ كيف تُعلم التطبيقات بعضها

الـ Webhook رسالة تلقائية ترسلها خدمة إلى تطبيقك في اللحظة التي يحدث فيها شيء ما. فعندما تنجح دفعة عميل، ترسل Stripe Webhook إلى عنوان في تطبيقك يقول "نجحت الدفعة، وهذه تفاصيلها"، فيتفاعل تطبيقك: يعلّم الطلب كمدفوع، ويرسل إيصالًا، ويفعّل الحساب. باختصار: الـ API هو أن يسأل تطبيقك خدمة أخرى سؤالًا؛ أما الـ Webhook فهو أن تستدعي الخدمة الأخرى تطبيقك لتخبره بشيء.

لماذا يهم عند البناء بالذكاء الاصطناعي

بمجرد أن يقبل تطبيقك مدفوعات، أو يستقبل نماذج من أداة أخرى، أو يتصل بخدمات مثل GitHub أو Shopify أو التقويم، ستصادف الـ Webhooks. وغالبًا ما تكون الطريقة الصحيحة لمعرفة أن شيئًا ما حدث — لكنها أيضًا المكان الذي تخطئ فيه التطبيقات المبنية بالذكاء الاصطناعي غالبًا بشكل خفي:

• نقطة النهاية تقبل أي طلب، فيستطيع أي شخص أن يزوّر حدث "تم الدفع".
• التطبيق يمنح الوصول من صفحة التحويل بعد الدفع بدلًا من الـ Webhook، فيحرم من دفع أولًا من يغلق المتصفح مبكرًا، ويحصل عليه مجانًا من يعثر على عنوان صفحة النجاح.
• يصل الحدث نفسه مرتين فيحصل العميل على طلبين أو رسالتين بريد.

ومعرفة طريقة عمل الـ Webhooks تتيح لك أن تطلب الحمايات مسبقًا.

تشبيه من الحياة اليومية: رسالة تسليم الطرد

يمكنك أن تعرف وصول طردك بطريقتين. يمكنك أن تمشي إلى الباب الأمامي كل عشر دقائق للتحقق (وهذا هو الاستطلاع Polling — أي أن يستدعي تطبيقك API مرارًا ليسأل "هل هناك جديد؟"). أو يمكن لشركة الشحن أن ترسل إليك رسالة نصية عند التسليم (وهذا هو Webhook).

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

كيف يعمل الـ Webhook، خطوة بخطوة

1. تنشئ نقطة نهاية في الخادم الخلفي لتطبيقك: عنوان مثل https://yourapp.com/webhooks/stripe يقبل طلبات POST.
2. تسجّل هذا العنوان لدى المزود وتختار الأحداث التي تريدها (مثلًا "اكتمل الدفع" و"أُلغي الاشتراك").
3. يعطيك المزود سر التوقيع. تخزّنه كسر على خادمك — انظر متغيرات البيئة والأسرار.
4. يقع حدث ما. يرسل المزود طلب HTTP إلى عنوانك يحتوي على جسم JSON يصف الحدث، مع ترويسة توقيع.
5. يتحقق تطبيقك من التوقيع، ويسجّل معرّف الحدث، ويرد برمز نجاح (200) بسرعة، ثم ينفذ العمل.
6. إذا لم يرد تطبيقك برمز نجاح، فكثير من المزودين يحاولون مرة أخرى لاحقًا.

التواقيع

التوقيع يثبت أن الطلب صادر من المزود ولم يُعدَّل. فـ Stripe، على سبيل المثال، تحسب HMAC (وهو نوع من البصمة المعتمدة على مفتاح) بخوارزمية SHA-256 على جسم الطلب والطابع الزمني، باستخدام سر التوقيع، وترسله في ترويسة Stripe-Signature. ويجري تطبيقك الحساب نفسه بنسخته من السر؛ فإذا تطابقت النتيجتان فالطلب أصلي. وبما أن الطابع الزمني موقّع أيضًا، يمكنك رفض الطلبات القديمة التي سجّلها أحد ليعيد إرسالها لاحقًا — وتعتمد مكتبات Stripe فترة سماح افتراضية مدتها خمس دقائق، وفقًا لوثائقها حتى سبتمبر 2026.

وتفصيل عملي: يُحسب التوقيع على جسم الطلب الخام. فإذا قام إطار العمل بتحليل JSON وإعادة تنسيقه قبل التحقق، يفشل الفحص. وهذا خلل شائع جدًا.

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

المزودون يختلفون، فراجع وثائق كل واحد منهم. وحتى سبتمبر 2026:

كما تقول وثائق Stripe إن الأحداث لا تصل بالضرورة بالترتيب الذي وقعت به، وإن الحدث نفسه قد يصل أكثر من مرة نادرًا، لذلك تنصح بتتبع معرّفات الأحداث.

والدرس العام ينطبق على أي مزود: قد تصل الأحداث متأخرة، وأكثر من مرة، وخارج الترتيب. ويجب أن يكون معالج الأحداث لديك idempotent — أي أن معالجة الحدث نفسه مرتين لها أثر مساوٍ لمعالجته مرة واحدة.

مثال تطبيقي: فتح دورة مدفوعة

تبيع دورة تدريبية عبر الإنترنت. يضغط طالب على شراء، ويدفع في صفحة الدفع المستضافة لدى Stripe، ويُعاد توجيهه إلى موقعك.

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

طريقة الـ Webhook:

1. عندما تؤكد Stripe الدفعة، ترسل حدث checkout.session.completed إلى /webhooks/stripe.
2. يتحقق الخادم الخلفي من التوقيع بسر التوقيع. إذا فشل، يرد بـ 400 ولا يفعل شيئًا.
3. يتحقق مما إذا كان معرّف الحدث قد عولج من قبل. إذا كان كذلك، يرد بـ 200 ويتوقف.
4. يحفظ معرّف الحدث، ويرد بـ 200، ثم يمنح الطالب الوصول ويرسل بريد ترحيب.
5. صفحة "شكرًا لك" تقول فقط "تم استلام الدفع — ستظهر دورتك بعد لحظات" وتتحقق من حالة وصول الطالب.

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

مصطلحات رئيسية

• نقطة النهاية (Endpoint): العنوان في تطبيقك الذي يستقبل الـ Webhooks.
• الحدث / الحمولة (Event / payload): ما الذي حدث، والبيانات التي تصفه (عادةً بصيغة JSON).
• سر التوقيع (Signing secret): السر المشترك المستخدم للتحقق من التواقيع.
• Idempotent (قابل للتكرار بأمان): آمن للتشغيل أكثر من مرة بالنتيجة نفسها.
• Polling (الاستطلاع): استدعاء API مرارًا لطلب التغييرات بدلًا من انتظار Webhook.
• Tunnel (نفق): أداة تمنح الحاسوب المحمول عنوانًا عامًا مؤقتًا حتى تصل الـ Webhooks إليه أثناء التطوير.

أخطاء شائعة ومفاهيم خاطئة

• عدم التحقق من التواقيع. عنوان نقطة النهاية ليس سرًا. التحقق هو ما يجعل الطلب موثوقًا.
• القيام بعمل بطيء قبل الرد. إرسال رسائل بريد أو توليد ملفات PDF قبل الرد قد يسبب انتهاء المهلة، فتتكرر المحاولات، فتنتج التكرارات.
• افتراض التسليم مرة واحدة وبالترتيب. سجّل معرّفات الأحداث ولا تعتمد على ترتيب وصولها.
• استخدام عنوان معاينة. الـ Webhooks تحتاج إلى عنوان عام ثابت. فالمعاينات الخاصة وlocalhost لا يمكن الوصول إليها من الإنترنت؛ استخدم عنوانك المنشور (أو نفقًا أثناء الاختبار).
• خلط أسرار الاختبار بأسرار الإنتاج. غالبًا ما يصدر المزودون أسرار توقيع مختلفة لوضعي الاختبار والإنتاج. احفظ الاثنين واستخدم الصحيح.
• الوثوق بالحمولة بشكل أعمى في القرارات المهمة. بالنسبة إلى الإجراءات عالية المخاطر، من المعقول أن تجلب أحدث حالة من API المزود بعد استلام الحدث.

ماذا تطلب من منشئ التطبيق بالذكاء الاصطناعي

أضف نقطة نهاية POST /webhooks/stripe على الخادم. تحقّق من توقيع Stripe باستخدام جسم الطلب الخام والسر STRIPE_WEBHOOK_SECRET. ارفض التواقيع غير الصالحة برمز 400. خزّن معرّف كل حدث وتجاوز الأحداث التي عولجت من قبل. ارد بـ 200 بسرعة، ثم عالج checkout.session.completed بتعليم الطلب كمدفوع وإرسال الإيصال. سجّل نوع الحدث. لا تمنح الوصول من صفحة نجاح الدفع.

ثم اختبره: أرسل حدثًا تجريبيًا من لوحة المزود، ثم أرسل الحدث نفسه مرة أخرى، وأرسل طلبًا بتوقيع خاطئ. الحدث الأول وحده يجب أن يغيّر شيئًا.

Webhooks في Mythex

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

الأسئلة