تخطي إلى المحتوى الرئيسي
عاجل
التقنية 6 دقائق قراءة 3 مشاهدة

شرح بوابات الدفع Webhooks وكيف تضمن معالجة المدفوعات بأمان دون تكرار (Idempotency)

أنماط التحقق من التوقيع الرقمي HMAC ومعالجة إعادة الإرسال في الأنظمة المالية

شرح بوابات الدفع Webhooks وكيف تضمن معالجة المدفوعات بأمان دون تكرار (Idempotency)
مشاركة المقال: واتساب تيليجرام إكس فيسبوك لينكد إن
إعلان ممول Google AdSense

تعتمد بوابات الدفع الحديثة على Webhooks لإخطار خادمك بنتيجة العملية المالية فور حدوثها، ولضمان الأمان المالي التام يجب تطبيق ثلاث قواعد صارمة: التحقق من التوقيع الرقمي (HMAC-SHA256) قبل أي معالجة، والاستجابة السريعة برمز 200 OK مع ترحيل العمل لطابور خلفي، وتخزين معرف الحدث لضمان عدم التنفيذ المكرر (Idempotency).

لماذا تفشل المعالجة الساذجة لإشعارات Webhooks المالية؟

يخطئ بعض المطورين بالاعتماد على صفحة إعادة التوجيه (Redirect URL) التي يعود إليها المتصفح بعد الدفع لتفعيل الطلب، متجاهلين أن المستخدم قد يغلق المتصفح أو ينقطع اتصاله قبل العودة. لذلك توفر بوابات الدفع إشعارات Webhooks المباشرة من خادم إلى خادم كمصدر الحقيقة الموثوق. لكن هذه الإشعارات تعمل وفق نموذج التسليم «مرة واحدة على الأقل» (At-least-once delivery)؛ فإذا تأخر خادمك في الرد لبضع ثوانٍ أو حدث اضطراب شبكي عابر، تفترض البوابة فشل التوصيل وتعيد إرسال الإشعار نفسه عدة مرات، وقد تصل الأحداث أحياناً بترتيب مختلف.

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

إعلان ممول Google AdSense

الركائز الأمنية الأساسية لتأمين نقطة استقبال 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 عند فشل الحفظ لتعيد البوابة الإرسال لاحقاً

التدقيق والمصالحة عدم حفظ سجل الإشعارات المستلمة أرشفة الأحداث مع مهمة مجدولة للاستعلام عن الطلبات المعلقة

إعلان ممول Google AdSense

مثال عملي: التحقق من التوقيع ومنع التكرار في 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 مالية موثوقة

  1. عطّل تحليل JSON التلقائي لمسار Webhook: احتفظ بالحمولة الخام (Raw Body) أولاً للتحقق الدقيق من توقيع HMAC-SHA256 قبل قراءة الحقول.
  2. ارفض التواقيع غير الصحيحة والطلبات المنتهية الصلاحية: أرجع رمز 401 أو 400 فور فشل التوقيع أو تجاوز نافذة الطابع الزمني المسموح بها.
  3. سجّل معرف الحدث بقيد UNIQUE: اعتمد على قاعدة البيانات كحكم نهائي لمنع التكرار بدلاً من الفحص المؤقت في الذاكرة فقط.
  4. استجب بسرعة بـ 200 OK وعالج في الخلفية: حافظ على زمن استجابة أقل من ثانية واحدة لمنع انتهاء مهلة البوابة وتكرار الإرسال غير الضروري.
  5. أضف مهمة مصالحة دورية (Reconciliation Job): أنشئ مهمة مجدولة تستعلم من API بوابة الدفع عن الطلبات المعلقة لفترة طويلة تحسباً لأي انقطاع مطوّل في خادمك.
في الأنظمة المالية، لا تفترض أبداً أن إشعار Webhook سيصل مرة واحدة فقط أو بالترتيب المثالي، ولا تثق بأي طلب وارد قبل مطابقة توقيعه المشفر.

أسئلة شائعة

  • السؤال: ماذا أفعل إذا تعطل خادمي مؤقتاً وفاتني إشعار Webhook؟ الإجابة: تعيد بوابات الدفع المحاولة تلقائياً وفق جدول تصاعدي (Exponential Backoff) لساعات أو أيام، كما ينبغي تشغيل مهمة مصالحة مجدولة للاستعلام من API البوابة عن الطلبات المعلقة.
  • السؤال: لماذا نتحقق من الطابع الزمني (Timestamp) داخل توقيع Webhook؟ الإجابة: لمنع هجمات إعادة الإرسال (Replay Attacks)؛ إذ يرفض الخادم أي إشعار مضى على توقيعه أكثر من نافذة زمنية قصيرة (عادة 5 دقائق) حتى لو كان التوقيع صحيحاً رياضياً.
  • السؤال: هل يمكن استخدام Idempotency Key عند إرسال طلبات الدفع الصادرة أيضاً؟ الإجابة: نعم، إرسال ترويسة Idempotency-Key فريدة عند إنشاء عملية دفع يضمن ألا تكرر البوابة سحب المبلغ إذا ضغط المستخدم مرتين أو انقطع الاتصال أثناء انتظار الرد.
  • السؤال: لماذا لا يكفي الاعتماد على قائمة عناوين IP الخاصة ببوابة الدفع؟ الإجابة: لأن عناوين IP قد تتغير دون إشعار مسبق أو تكون مشتركة عبر خدمات سحابية، بينما يثبت توقيع HMAC-SHA256 المشفر هوية المرسل وسلامة محتوى الرسالة من التلاعب.
إعلان ممول Google AdSense
عبدالرحمن شوقي

عبدالرحمن شوقي

كاتب في ايجي مونيتور

المدير العام لمنصة ايجي مونيتور.

ما رأيك بهذا المقال؟ سجل الدخول للتفاعل

التعليقات (0)

أضف تعليقك

كن أول من يعلق على هذا المقال!

مقالات ذات صلة

المزيد من التقنية
عبدالرحمن شوقي 3 مشاهدة

حماية واجهات API عبر Rate Limiting ومنع هجمات الإغراق في الخوادم

تعلّم كيفية حماية واجهات API من هجمات الإغراق وسوء الاستخدام عبر تطبيق Rate Limiting باستخدام خوارزميات Token Bucket وSliding Window مع Redis.

اقرأ المزيد 6 دقائق قراءة
عبدالرحمن شوقي 5 مشاهدة

التواصل اللحظي في الويب: الفرق بين WebSockets وSSE وLong Polling

مقارنة عملية شاملة بين WebSockets وServer-Sent Events (SSE) وLong Polling لبناء ميزات التواصل اللحظي، الإشعارات، والبث الحي للبيانات في تطبيقات الويب.

اقرأ المزيد 6 دقائق قراءة
عبدالرحمن شوقي 4 مشاهدة

تسريع المواقع عبر Redis Caching: استراتيجيات التخزين المؤقت وإبطال الكاش

استعرض أهم استراتيجيات التخزين المؤقت عبر Redis مثل Cache-Aside وWrite-Through، وتعلّم تقنيات إبطال الكاش Cache Invalidation ومنع عاصفة الطلبات.

اقرأ المزيد 6 دقائق قراءة
عبدالرحمن شوقي 4 مشاهدة

معمارية Monolith مقابل Microservices: متى تحتاج لتقسيم نظامك؟

دليل قرار معماري للمقارنة بين Monolith وMicroservices وModular Monolith، يستعرض التكاليف الخفية، اتساق البيانات، ومعايير التوقيت الصحيح لتقسيم النظام.

اقرأ المزيد 6 دقائق قراءة
عبدالرحمن شوقي 5 مشاهدة

بناء واجهات API احترافية في Node.js: مقارنة Express وNestJS وFastify

مقارنة عملية شاملة بين Express 5 وFastify وNestJS لبناء واجهات API احترافية في Node.js، تغطي الأداء، دعم TypeScript، الهيكلة المعمارية، ومعايير الاختيار.

اقرأ المزيد 7 دقائق قراءة
عبدالرحمن شوقي 5 مشاهدة

فعالية $1M Perks Station في ببجي موبايل فلاش 2026: دليلك الكامل للمكافآت المجانية وهدايا الإطلاق

دليلك الشامل لفعالية $1M Perks Station في ببجي موبايل فلاش 2026: طريقة الحصول على مكافآت الإطلاق المجانية وهدايا التسجيل المسبق والجوائز الحصرية.

اقرأ المزيد 6 دقائق قراءة