Webhook تبدو بسيطة: مزود يرسل POST إلى endpoint لديك. لكن الإنتاج يضيف مشاكل مثل retries، ترتيب غير مضمون، duplicate events، توقيع، timeout، وتحولات schema. قبل ربط Workflow حقيقية، اختبر العقد نفسه من أداة API أو Web Postman ضمن بيئة آمنة. الهدف ليس التأكد أن 200 يعود مرة واحدة، بل أن receiver تتعامل مع الحالات الطبيعية والفشل بدون تكرار أثر أو فقد حدث.
1 و 2: Authentication والتوقيع
اختبر الطلب الصحيح، ثم طلبًا بدون secret أو بتوقيع خاطئ. إذا كان المزود يستخدم HMAC، تحقق من raw body بالطريقة الموثقة ولا تعيد stringify قبل التحقق. افصل سر Webhook عن API keys الأخرى.
3 و 4: Duplicate و Idempotency
أرسل نفس event ID مرتين وتأكد أن الأثر يحدث مرة واحدة. ثم أرسل نفس ID مع body مختلفة وتأكد أن النظام يرفض التناقض أو يسجله. معظم مزودي Webhooks يعيدون المحاولة عند timeout، لذلك duplicates سلوك متوقع وليست حالة نادرة.
5 و 6: Timeout و Retry
اجعل endpoint تتأخر عمدًا وشاهد سلوك المزود. Receiver جيدة تعيد acknowledgment سريعًا ثم تضع العمل الثقيل في queue، بدل إبقاء الاتصال مفتوحًا. اختبر backoff وأقصى عدد محاولات إن كان المزود يوثقها.
خطوات عملية
- أرسل request صحيحة.
- اختبر signature خاطئة.
- كرر نفس event.
- اجعل endpoint بطيئة.
- أعد 500 مؤقتًا.
- راقب retries.
- تحقق أن الأثر لم يتكرر.
7: ترتيب الأحداث
لا تفترض وصول created قبل updated أو deleted دائمًا. استخدم version/timestamp أو state fetch عند الحاجة. أرسل events بترتيب معكوس في الاختبار.
8: Schema evolution
أضف field غير معروفة وتأكد أن parser لا ينهار. ثم اختبر field اختيارية مفقودة. Contract قوية تتعامل مع extensions وتتحقق فقط مما تحتاجه فعليًا.
9: Replay
أعد إرسال request قديمة بتوقيع صحيح إن كان البروتوكول يسمح بمحاكاة ذلك، وتأكد أن timestamp window أو event ID تمنع تنفيذًا جديدًا عندما يجب منعه.
10: Observability
يجب أن تستطيع ربط كل incoming event ب ـrequest ID و event ID ونتيجة المعالجة بدون تسجيل secrets أو payload حساسة كاملة. وجود dead-letter أو صفحة فشل يسهل إعادة المعالجة اليدوية.
قائمة مراجعة
- Signature verified.
- Duplicates آمنة.
- Timeout معروف.
- Retry لا يكرر الأثر.
- الترتيب غير مفترض.
- Schema مرنة.
- Replay محدودة.
- Logs قابلة للتتبع.
تحقق من Raw Body عند حساب التوقيع
كثير من موفري Webhooks يوقعون bytes الأصلية للطلب. إذا قام framework بتحويل JSON ثم أعدت stringify، قد تتغير المسافات أو ترتيب الحقول وتفشل المقارنة. احتفظ بال raw body لمسار التحقق فقط، ثم parse بعد نجاح التوقيع، ولا تسجل raw payload إذا كانت تحتوي بيانات حساسة.
حدد نافذة Replay بوضوح
إذا كان التوقيع يحتوي timestamp، ارفض requests القديمة خارج window معقولة حتى لو كان HMAC صحيحًا. لكن راعِ clock skew بين الأنظمة. اجمع timestamp مع event ID و idempotency بحيث تمنع replay قديمة من إعادة تنفيذ أثر مشروع سابق.
شارك في تقييم ونقاش المقال
رأيك يضيف قيمة للمقال ويساعدنا على تحسين المحتوى والنقاش حوله.
النقاش
جارٍ تحميل التعليقات…