التحقق من توقيع Webhook في بوابة دفتر كاش: دليل المطوّر

للتحقق من توقيع Webhook في بوابة دفتر كاش احسب HMAC-SHA256 على جسم الطلب الخام بمفتاحك السري، وقارنه بالترويسة X-VodaCash-Signature بمقارنة آمنة زمنيًا. فإن تطابقا فالإشعار أصلي، وإلا فارفضه ولا تغيّر حالة أي طلب. هذا الدليل موجه للمطوّر الذي يبني تكاملًا مخصصًا مع بوابة الدفع بدل إضافة ووكومرس الجاهزة.

لماذا التحقق من التوقيع ضروري؟

رابط الـ Webhook في متجرك يمكن الوصول إليه من الإنترنت. وإذا لم تتحقق من توقيع كل طلب يصل إليه، فبإمكان أي طرف إرسال طلب مزوّر يدّعي نجاح الدفع، فتشحن طلبات لم تُدفع. التوقيع هو الدليل الوحيد على أن الإشعار صدر من البوابة فعلًا.

من أين تحصل على المفاتيح؟

من لوحة البوابة ← المطوّرين تنسخ مفتاحين مختلفين. الأول مفتاح التاجر لمصادقة طلبات الـ API، والثاني المفتاح السري للتوقيع وهو ما تحتاجه هنا. كلاهما يبقى على سيرفرك فقط. ثم تضع رابط الـ Webhook الخاص بمتجرك:

كيف يعمل توقيع HMAC؟

ترسل البوابة مع كل إشعار ثلاث ترويسات:

• X-VodaCash-Signature: توقيع HMAC-SHA256 (بصيغة hex) لجسم الطلب الخام.
• X-VodaCash-Delivery-Id: رقم ثابت لكل إشعار، ويتكرر عند إعادة المحاولة لنفس الإشعار.
• X-VodaCash-Attempt: رقم المحاولة، وتبدأ من 1.

أعد حساب التوقيع بالمفتاح السري نفسه وقارنه بالوارد، ثم تجاهل إشعارات بيئة التجربة:

// Node.js (Express) — verify the raw body, then skip sandbox events
const crypto = require('crypto');

function isValidWebhook(rawBody, receivedSignature, secretKey) {
  const expected = crypto.createHmac('sha256', secretKey).update(rawBody).digest('hex');
  const received = receivedSignature || '';
  return received.length === expected.length &&
         crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

// after verification:
// if (event.status === 'completed' && !event.test_mode) markOrderPaid(...)

أخطاء شائعة عند التنفيذ

الرد وإعادة المحاولة والمعالجة المتكررة

رد بأي كود 2xx خلال 10 ثوانٍ. وإن لم تفعل، تعيد البوابة المحاولة: ثلاث محاولات سريعة متتالية، ثم إعادة تلقائية بعد 5 دقائق، و30 دقيقة، وساعتين، و6 ساعات، و24 ساعة، أي 8 محاولات إجمالًا. بعدها تستطيع إعادة الإرسال يدويًا.

قد يصلك الإشعار الواحد أكثر من مرة، بسبب إعادة المحاولة أو الإرسال اليدوي. لذلك اجعل المعالجة idempotent: إذا كان الطلب معلَّمًا مدفوعًا أو ملغيًا بالحالة نفسها فتجاهل الإشعار. ويفيدك رقم X-VodaCash-Delivery-Id مع event وpayment_id في منع المعالجة المزدوجة.

ماذا عن إضافة ووكومرس؟

إذا كان متجرك على ووكومرس فلا تحتاج إلى كتابة هذا الكود بنفسك، فالإضافة الجاهزة تتحقق من الترويسة على الجسم الخام وتقارن المبلغ وpayment_id قبل تحديث الطلب. هذا الدليل لمن يبني تكاملًا مخصصًا.

قائمة مراجعة قبل الإطلاق

قبل أن تنقل التكامل إلى الإنتاج، راجع هذه النقاط بالترتيب:

1. احفظ المفتاح السري في متغيرات البيئة لا في الكود ولا في المتصفح.
2. اقرأ جسم الطلب خامًا قبل أي تحليل JSON، واحسب التوقيع عليه.
3. قارن التوقيع بمقارنة آمنة زمنيًا ثم ارفض أي طلب غير مطابق.
4. تحقق من timestamp وارفض الإشعار الأقدم من 5 دقائق.
5. تجاهل الإشعار إذا كان test_mode قيمته true.
6. طابِق رقم الطلب والمبلغ مع بياناتك، ثم حدّث الحالة مرة واحدة فقط.
7. أرجع كود 2xx سريعًا، وانقل العمل الثقيل إلى مهمة خلفية.
8. بدّل مفتاح التجربة بالمفتاح الحي قبل الإطلاق.

تابع كل محاولة إرسال

يعرض سجل إرسال الـ Webhooks في لوحة البوابة كل محاولة مع رمز الاستجابة، ويمكنك إعادة إرسال أي إشعار فشل تسليمه:

للأمثلة الكاملة بلغات PHP وPython وNode.js، راجع توثيق المطوّرين. وللتعرف على الصورة الأوسع لحماية حسابك اقرأ كيف تحميك بوابة الدفع من عمليات النصب، أو ابدأ بالنهج الأسهل في ربط ووكومرس بفودافون كاش وإنستاباي. وإن كان لديك محل أيضًا، فتعرّف على إدارة المحافظ لمطابقة الدرج.

أسئلة شائعة