اختبار Webhooks

لماذا يهم

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

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

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

في دروس REST كان العميل يسأل والخادم يجيب. أما Webhook فيعكس الأدوار: خادم المزوّد هو العميل، ونقطة نهاية المستهلك هي التي تستقبل الطلب. ويُقرّ المستهلك باستلام التسليم بأن يرد سريعاً برمز حالة 2xx؛ أما أي رمز آخر (3xx أو 4xx أو 5xx) أو انتهاء المهلة (Timeout) أو رفض الاتصال فيُعدّ في الغالب تسليماً فاشلاً.

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

وإعادة المحاولة تعني أن التسليم يتم «مرة واحدة على الأقل» (At least once): فإذا أنجز المستهلك العمل لكن ردّه ضاع أو تأخر، يصل الحدث نفسه مجدداً. ولكل حدث في العادة معرّف (Event id) يبقى نفسه في كل إعادة محاولة (وبعض المزوّدين يضيفون معرّفاً منفصلاً لكل محاولة)، وبهذا المعرّف يُكتشف التكرار. والترتيب غير مضمون عادةً أيضاً: فقد يصل payment.succeeded المُعاد بعد payment.refunded الذي تلاه.

تساوي الأثر: لكل حدث أثر واحد

تكون المعالجة متساوية الأثر (Idempotent) عندما يكون لمعالجة الحدث مرتين الأثر نفسه لمعالجته مرة واحدة، كما في طرق HTTP المتكافئة. والتصميم المعتاد يخزّن معرّف الحدث في جدول عليه قيد تفرّد (Unique constraint)، وهو قاعدة في قاعدة البيانات ترفض صفاً ثانياً بالقيمة نفسها. فإذا كان المعرّف موجوداً، لا يفعل المستهلك شيئاً ويرد مع ذلك بـ 2xx؛ لأن رمز الخطأ لن يؤدي إلا إلى أن يعيد المزوّد محاولة حدث عولج من قبل. واسأل ماذا يحدث إذا خُزّن المعرّف ثم فشل العمل نفسه: يجب ألا تُتجاهَل إعادة المحاولة على أنها تكرار، وإلا ضاع الحدث.

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

التحقق من التوقيع

يوقّع كثير من المزوّدين كل تسليم بـ HMAC (RFC 2104)، وهو تجزئة (Hash) تُحسب بمفتاح سرّي، فلا يستطيع إنتاج القيمة الصحيحة إلا من يملك المفتاح، وتغيير بايت واحد من الرسالة يغيّر القيمة كلياً. وفي الغالب تكون HMAC-SHA256، بسرّ لا يعرفه إلا المزوّد والمستهلك، على الجسم الخام (Raw body) كما هو تماماً، وكثيراً ما يسبقه طابع زمني (Timestamp) بتوقيت Unix، أي عدد الثواني منذ 1 يناير 1970 بالتوقيت العالمي (UTC). ويعيد المستهلك حساب HMAC على البايتات التي استلمها ويقارن. والتطابق يدل على أن المرسل يعرف السر وأن الجسم لم يتغير؛ ورفض الطوابع الزمنية القديمة يحدّ من إعادة إرسال طلب ملتقَط. ويوقّع المزوّدون عادةً كل محاولة من جديد، فتحمل إعادة المحاولة بعد ساعات طابعاً زمنياً جديداً. وتحقّق على البايتات الخام: فالمعالج الذي يعيد تسلسل JSON (Re-serialization) أولاً يرفض تسليمات صالحة مسافاتها أو ترتيب مفاتيحها غير معتاد. والمخطط أدناه توضيحي: فكل مزوّد يوثّق ترويساته وصيغته الخاصة.

secret     shared value from the provider settings (test mode)
timestamp  1790000000, sent in the Pay-Timestamp header
input      "1790000000." + raw body bytes, exactly as received
signature  hex( HMAC-SHA256(secret, input) ), sent in Pay-Signature

consumer   recomputes over the raw bytes it received, compares with the
           header, and rejects a timestamp outside the tolerance window

جرّبها: محلّل توقيعات Webhook جرّبها: مولّد HMAC

الاختبار بنقطة التقاط

نقطة الالتقاط (Capture endpoint)، وتُسمّى كثيراً Request bin، عنوان URL عام مؤقت يسجّل كل طلب يصله. سجّله عنواناً لـ Webhook في وضع الاختبار (Test mode) لدى المزوّد، ثم أطلق حدثاً، فترى التسليم الحقيقي: الطريقة والترويسات والجسم الخام والتوقيت. وهذا يختبر جانب المزوّد قبل أن يوجد المستهلك: قارن الحمولة بالتوثيق، وتحقّق من توقيعها بسرّ الاختبار.

ثم يصبح التسليم الملتقَط بيانات اختبار للمستهلك. أعد إرساله (Replay)، أي أرسل الطريقة والترويسات والجسم الخام نفسها مرة أخرى، بـ cURL مثلاً: دون تغيير وداخل نافذة الطابع الزمني لاختبار التكرار، وبعد انقضاء النافذة لاختبار رفض التسليمات القديمة، ومع تغيير بايت واحد لاختبار الرفض. فداخل النافذة لا يكون خاطئاً إلا ما غيّرته أنت؛ أما خارجها فالطابع الزمني القديم وحده يسبّب الرفض. ووقّع نسخك الخاصة بأداة HMAC. ولرؤية إعادة المحاولة، أفشِل التسليم عمداً (أوقف المستهلك، أو اجعله يرد بـ 503، أو وجّه المزوّد إلى نقطة نهاية تعيد رمز 5xx)، ثم اقرأ المحاولات في سجل التسليم لدى المزوّد.

• ترد نقطة الالتقاط عادةً بـ 200 على كل شيء: فهي تثبت ما أرسله المزوّد، لا أن المستهلك لديك يعمل.
• استخدم وضع الاختبار وأسرار الاختبار وبيانات مصطنعة فقط، لأن التسليمات الملتقَطة تُخزَّن على خادم لبعض الوقت. واطلب تدوير أي سرّ يتسرّب.

جرّبها: مختبِر Webhook جرّبها: فاحص Webhook جرّبها: منسّق حمولات Webhook جرّبها: محاكي رموز حالة API

مثال تطبيقي: اختبارات Webhook للدفع

المتطلب: «عند وصول حدث payment.succeeded صالح، غيّر حالة الطلب إلى مدفوع وأرسل إيصالاً واحداً. التسليمات موقّعة بـ HMAC-SHA256 على الطابع الزمني والجسم، وتُرفض الطوابع الزمنية الأقدم من 300 ثانية. ويعيد المزوّد المحاولة عند أي استجابة غير 2xx وعند أي استجابة تتأخر أكثر من 10 ثوانٍ». وهذا تسليم ملتقَط:

• W1: تسليم جديد صالح ← 2xx خلال 10 ثوانٍ، والطلب 1042 مدفوع (PAID)، وإيصال واحد.
• W2: إعادة إرسال التسليم نفسه، وW3: نسختان في وقت واحد ← 2xx، ويبقى إيصال واحد ومعرّف حدث واحد مخزَّن.
• W4: تغيير المبلغ إلى "1.00" دون إعادة التوقيع، أو غياب التوقيع، أو سرّ آخر ← 4xx، والطلب دون تغيير، والرفض مسجَّل.
• W5: توقيع صالح وطابع زمني عمره 300 ثانية ثم 301 ثانية ← يُقبل ثم يُرفض (تحليل القيم الحدّية بالصيغة الثنائية: عبارة «الأقدم من 300» تُبقي 300 في القسم المقبول). ويزداد العمر أثناء انتقال الطلب، لذا اسأل كيف يُقاس ويُقرَّب.
• W6: معالجة payment.refunded قبل وصول payment.succeeded المُعاد ← يبقى الطلب مُسترَداً (REFUNDED).
• W7: 503 على المحاولة الأولى ← يعيد المزوّد المحاولة فتنجح، وإيصال واحد.

POST /webhooks/payments HTTP/1.1
Host: shop.example
Content-Type: application/json
Pay-Timestamp: 1790000000
Pay-Signature: sha256=<hex HMAC-SHA256 of "1790000000." + raw body>

{
  "id": "evt_7f3a91",
  "type": "payment.succeeded",
  "data": { "order_id": 1042, "amount": "190.00", "currency": "SAR" }
}

أسئلة شائعة

المراجع

• RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.
• RFC 2104: HMAC: Keyed-Hashing for Message AuthenticationIETF · 1997بناء HMAC: كيف يُنتج مفتاح سري ودالة تجزئة رمز مصادقة للرسالة.
• ISTQB Certified Tester Foundation Level (CTFL) v4.0ISTQB · 2023المنهج التأسيسي لاختبار البرمجيات: مستويات الاختبار وأنواعه وتقنيات تصميم الاختبارات وإدارة الاختبار والأدوات.