Webhooks: اختبار التوقيع وإعادة المحاولة محليًا

Webhook يبدو بسيطًا: HTTP request يصل عند حدث. لكن الإنتاج يحتاج تحققًا من المصدر، مقاومة إعادة الإرسال، واستجابة سريعة. الاختبار المحلي يجب أن يحاكي هذه الحالات لا مجرد استقبال JSON مرة واحدة.

تحقق من التوقيع على raw body

كثير من المزودين يحسبون HMAC على bytes الأصلية، لذلك parsing ثم إعادة stringify قد يكسر التحقق.

اختبر replay

أرسل نفس event ID مرتين وتأكد أن الأثر لا يتكرر.

حاكِ retries

ارجع 500 أو timeout وشاهد كيف يعيد المزود الإرسال.

استخدم tunnel بحذر

عند تعريض localhost، لا تستخدم secrets إنتاجية بلا حماية.

سيناريو تطبيقي قبل الاعتماد

تخيل المهمة تعمل عشرات المرات يوميًا، ويحدث في إحدى المرات timeout بعد خطوة لها أثر خارجي. التصميم الجيد يجب أن يعرف أين توقف وما الذي تم بالفعل. في موضوع «Webhooks: اختبار التوقيع وإعادة المحاولة محليًا»، نفّذ تجربة صغيرة قبل تعميم القرار. ابدأ بـ1- احفظ raw request.، 2- تحقق signature.، 3- تحقق timestamp.، ثم سجل النتيجة قبل توسيع النطاق. لا تحاول تحسين كل شيء في أول Run؛ المطلوب أولًا إنشاء حالة مرجعية تستطيع العودة إليها ومقارنتها. عندما تنجح التجربة، كررها مرة ثانية بنفس الشروط للتأكد أن النتيجة لم تكن صدفة أو أثر Cache أو حالة مؤقتة.

كيف تقيس نجاح التجربة؟

راقب نسبة النجاح من أول محاولة، عدد retries، زمن كل خطوة، عدد التدخلات اليدوية، وحالات التكرار أو الـloop. هذه المقاييس أهم من مجرد انتهاء Run واحدة بنجاح. حوّل النقاط الموجودة في المقال إلى مؤشرات قابلة للرصد: timestamp قد يدخل التوقيع.؛ secret لا يُسجل.؛ comparison يفضل timing-safe.. احتفظ بالقياسات مع timestamp ونسخة التطبيق أو البيئة، لأن مقارنة أرقام من إصدارات أو شروط مختلفة قد تعطي استنتاجًا خاطئًا. وإذا كانت النتيجة رقمية، استخدم أكثر من عينة بدل أفضل أو أسوأ قيمة منفردة.

عند الفشل: ماذا تراجع أولًا؟

عند الفشل، لا تبدأ من أول Workflow تلقائيًا. تحقق من آخر checkpoint والأثر الخارجي، ثم اختر retry أو resume أو manual review وفق حالة مؤكدة. عند التحقيق استخدم هذه القائمة كحد أدنى: signature صحيح.؛ duplicate آمن.؛ response سريع.؛ processing async عند الحاجة.. سجل ما الذي جربته وما الذي لم يتغير بعد التجربة. هذه المعلومة تمنع الفريق من إعادة نفس المحاولات وتساعد على تحديد ما إذا كان الخطأ في الإعداد أو الأداة أو الشبكة أو بيانات المهمة.

متى تعتمد القرار على نطاق أوسع؟

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