تعتمد بوابات الدفع الحديثة على Webhooks لإخطار خادمك بنتيجة العملية المالية فور حدوثها، ولضمان الأمان المالي التام يجب تطبيق ثلاث قواعد صارمة: التحقق من التوقيع الرقمي (HMAC-SHA256) قبل أي معالجة، والاستجابة السريعة برمز 200 OK مع ترحيل العمل لطابور خلفي، وتخزين معرف الحدث لضمان عدم التنفيذ المكرر (Idempotency).
لماذا تفشل المعالجة الساذجة لإشعارات Webhooks المالية؟
يخطئ بعض المطورين بالاعتماد على صفحة إعادة التوجيه (Redirect URL) التي يعود إليها المتصفح بعد الدفع لتفعيل الطلب، متجاهلين أن المستخدم قد يغلق المتصفح أو ينقطع اتصاله قبل العودة. لذلك توفر بوابات الدفع إشعارات Webhooks المباشرة من خادم إلى خادم كمصدر الحقيقة الموثوق. لكن هذه الإشعارات تعمل وفق نموذج التسليم «مرة واحدة على الأقل» (At-least-once delivery)؛ فإذا تأخر خادمك في الرد لبضع ثوانٍ أو حدث اضطراب شبكي عابر، تفترض البوابة فشل التوصيل وتعيد إرسال الإشعار نفسه عدة مرات، وقد تصل الأحداث أحياناً بترتيب مختلف.
بدون حماية ضد التكرار، يؤدي وصول إشعار النجاح مرتين إلى شحن الطلب مرتين، أو إضافة الرصيد مضاعفاً إلى محفظة العميل، أو إصدار فاتورتين مكررتين، وهي أخطاء مالية يصعب تداركها محاسبياً وتضر بثقة العملاء.
الركائز الأمنية الأساسية لتأمين نقطة استقبال Webhook
- التحقق من التوقيع بالحمولة الخام (Raw Body): احسب توقيع
HMAC-SHA256باستخدام المفتاح السري على نص الطلب الخام قبل تحليله كـ JSON، لأن إعادة تنسيق JSON تغير البايتات وتبطل التوقيع. - المقارنة بزمن ثابت (Constant-Time Comparison): استخدم دوال آمنة مثل
crypto.timingSafeEqualفي Node.js أوhash_equalsفي PHP بدلاً من معامل المساواة العادي لمنع هجمات التوقيت (Timing Attacks). - التحقق من الطابع الزمني لمنع إعادة الإرسال: افحص الطابع الزمني المرفق داخل التوقيع وارفض أي إشعار أقدم من 5 دقائق لصد هجمات إعادة الإرسال (Replay Attacks).
- قفل التفرد في قاعدة البيانات: أنشئ جدول
processed_webhooksمزوداً بعمود فريد (UNIQUE) لمعرف الحدث (event_id) بحيث تمنع قاعدة البيانات نفسها أي تنفيذ مزدوج حتى لو وصل الطلبان في الجزء نفسه من الثانية.
مقارنة خطوات معالجة Webhook: غير الآمنة مقابل المعيارية
يوضح الجدول التالي الفارق العملي بين التطبيق غير الآمن والممارسة القياسية المعتمدة في الأنظمة المالية الإنتاجية عبر مراحل معالجة الإشعار كافة:
المرحلة الممارسة غير الآمنة الممارسة القياسية الآمنة
التحقق من المصدر الاعتماد على قائمة عناوين IP فقط أو بدون تحقق التحقق من توقيع HMAC-SHA256 على الحمولة الخام والطابع الزمني
توقيت الاستجابة إنشاء الفاتورة وإرسال البريد وتحديث المخزون قبل الرد التحقق والحفظ ثم الرد فوراً بـ 200 OK والترحيل إلى Queue
قد يعجبك ايضا
منع التكرار (Idempotency) تحديث حالة الطلب مباشرة دون فحص مسبق تسجيل Event ID بقيد UNIQUE داخل معاملة قاعدة بيانات ذرية
معالجة الأعطال تجاهل الأخطاء أو إعادة رمز 200 رغم فشل الحفظ إرجاع رمز 5xx عند فشل الحفظ لتعيد البوابة الإرسال لاحقاً
التدقيق والمصالحة عدم حفظ سجل الإشعارات المستلمة أرشفة الأحداث مع مهمة مجدولة للاستعلام عن الطلبات المعلقة
مثال عملي: التحقق من التوقيع ومنع التكرار في Node.js
يوضح الكود التالي نمطاً إنتاجياً نظيفاً يبدأ بالتحقق الآمن من التوقيع الرقمي عبر مقارنة ثابتة الزمن، ثم يستخدم قيد التفرد في PostgreSQL لضمان معالجة الحدث مرة واحدة فقط قبل دفعه إلى طابور المعالجة الخلفية:
import crypto from 'node:crypto';
const expectedSig = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(req.rawBody)
.digest('hex');
const receivedBuf = Buffer.from(signature, 'utf8');
const expectedBuf = Buffer.from(expectedSig, 'utf8');
if (receivedBuf.length !== expectedBuf.length || !crypto.timingSafeEqual(receivedBuf, expectedBuf)) {
return res.status(401).send('توقيع غير صالح');
}
const inserted = await db.query(
'INSERT INTO processed_webhooks (event_id, payload) VALUES ($1, $2) ON CONFLICT (event_id) DO NOTHING RETURNING id',
[event.id, req.body]
);
if (inserted.rowCount === 0) {
return res.status(200).send('تمت المعالجة مسبقاً');
}
await paymentQueue.add('fulfill-order', { eventId: event.id });
return res.status(200).send('تم الاستلام بنجاح');
التعامل مع المعاملات المتزامنة والمهام الخلفية
حتى بعد الاستلام الآمن للـ Webhook، قد تقع مشكلات دقيقة إذا فشل العامل الخلفي (Worker) في منتصف تنفيذ العملية أو إذا وصل إشعاران متزامنان لنفس الطلب.
الذرية (Atomicity) في تحديث حالة الطلب
اجعل تسجيل معرف الحدث وتحديث حالة الطلب من «معلّق» إلى «مدفوع» داخل معاملة قاعدة بيانات واحدة (Transaction)، أو استخدم تحديثاً مشروطاً مثل WHERE status = 'pending' لضمان عدم تنفيذ التفعيل مرتين حتى في حالات إعادة تشغيل مهام الطابور.
ملاحظة حول مفاتيح Idempotency الصادرة
لا تقتصر فكرة Idempotency على استقبال Webhooks فقط؛ بل يجب أيضاً إرسال ترويسة Idempotency-Key فريدة لكل محاولة إنشاء دفعة صادرة من خادمك نحو البوابة لمنع سحب المبلغ مرتين عند إعادة المحاولة.
خطوات عملية لبناء منظومة Webhooks مالية موثوقة
- عطّل تحليل JSON التلقائي لمسار Webhook: احتفظ بالحمولة الخام (Raw Body) أولاً للتحقق الدقيق من توقيع HMAC-SHA256 قبل قراءة الحقول.
- ارفض التواقيع غير الصحيحة والطلبات المنتهية الصلاحية: أرجع رمز
401أو400فور فشل التوقيع أو تجاوز نافذة الطابع الزمني المسموح بها. - سجّل معرف الحدث بقيد UNIQUE: اعتمد على قاعدة البيانات كحكم نهائي لمنع التكرار بدلاً من الفحص المؤقت في الذاكرة فقط.
- استجب بسرعة بـ 200 OK وعالج في الخلفية: حافظ على زمن استجابة أقل من ثانية واحدة لمنع انتهاء مهلة البوابة وتكرار الإرسال غير الضروري.
- أضف مهمة مصالحة دورية (Reconciliation Job): أنشئ مهمة مجدولة تستعلم من API بوابة الدفع عن الطلبات المعلقة لفترة طويلة تحسباً لأي انقطاع مطوّل في خادمك.
في الأنظمة المالية، لا تفترض أبداً أن إشعار Webhook سيصل مرة واحدة فقط أو بالترتيب المثالي، ولا تثق بأي طلب وارد قبل مطابقة توقيعه المشفر.
أسئلة شائعة
- السؤال: ماذا أفعل إذا تعطل خادمي مؤقتاً وفاتني إشعار Webhook؟ الإجابة: تعيد بوابات الدفع المحاولة تلقائياً وفق جدول تصاعدي (Exponential Backoff) لساعات أو أيام، كما ينبغي تشغيل مهمة مصالحة مجدولة للاستعلام من API البوابة عن الطلبات المعلقة.
- السؤال: لماذا نتحقق من الطابع الزمني (Timestamp) داخل توقيع Webhook؟ الإجابة: لمنع هجمات إعادة الإرسال (Replay Attacks)؛ إذ يرفض الخادم أي إشعار مضى على توقيعه أكثر من نافذة زمنية قصيرة (عادة 5 دقائق) حتى لو كان التوقيع صحيحاً رياضياً.
- السؤال: هل يمكن استخدام Idempotency Key عند إرسال طلبات الدفع الصادرة أيضاً؟ الإجابة: نعم، إرسال ترويسة
Idempotency-Keyفريدة عند إنشاء عملية دفع يضمن ألا تكرر البوابة سحب المبلغ إذا ضغط المستخدم مرتين أو انقطع الاتصال أثناء انتظار الرد. - السؤال: لماذا لا يكفي الاعتماد على قائمة عناوين IP الخاصة ببوابة الدفع؟ الإجابة: لأن عناوين IP قد تتغير دون إشعار مسبق أو تكون مشتركة عبر خدمات سحابية، بينما يثبت توقيع HMAC-SHA256 المشفر هوية المرسل وسلامة محتوى الرسالة من التلاعب.
التعليقات (0)
أضف تعليقك