ويب هوك مدفوعات العملات الرقمية: الأحداث والأمان وتنفيذ الطلبات بموثوقية

ويب هوك مدفوعات العملات الرقمية طلبات HTTP ترسلها بوابة الدفع إلى خادمك كلما تغيّرت حالة فاتورة: اكتُشف التحويل، أو تأكد على السلسلة، أو جاء ناقصًا أو زائدًا، أو انتهت صلاحية الفاتورة. يتحقق معالجك من التوقيع، ويحدّث الطلب، ويطلق التسليم. ولأن المدفوعات الرقمية تصل بشكل غير متزامن، بعد دقائق من مغادرة العميل صفحتك، فإن الويب هوك هو مصدر الحقيقة لا المتصفح.

يركز هذا الدليل على جانب الويب هوك من التكامل: الأحداث المتوقعة، وكيفية التحقق منها، وكيف تبقى المعالجة آمنة عندما يصل الحدث نفسه مرتين، وكيفية الاختبار والمراقبة. لإنشاء الفواتير، راجع دليلنا عن تكامل API المدفوعات الرقمية.

لماذا الويب هوك بدل الاستطلاع أو إعادة التوجيه؟

• إعادة التوجيه ليست دليلًا — عودة العميل إلى صفحة «شكرًا» لا تقول شيئًا عن وصول المال.
• الاستطلاع مهدر — سؤال الـ API كل بضع ثوانٍ عن كل فاتورة مفتوحة لا يتوسع ويبقى متأخرًا.
• الويب هوك دفع مباشر — تُبلغك البوابة لحظة حدوث أي تغيير مع توقيع يمكنك التحقق منه.

الأحداث التي ستستقبلها

هذه أسماء الأحداث في mistKET. تستخدم البوابات الأخرى حالات مشابهة بأسماء مختلفة، لذا اربطها بحالات طلبك في مكان واحد.

التحقق من التوقيع

يمكن لأي شخص إرسال طلب POST إلى رابط عام، لذا يجب توثيق كل ويب هوك. توقّع mistKET كل إرسال بـ HMAC-SHA256 وترسل هذه الترويسات:

• X-Mistket-Event — اسم الحدث.
• X-Mistket-Timestamp — وقت Unix الداخل في التوقيع.
• X-Mistket-Signature — sha256= يليها HMAC لـ {timestamp}.{raw body} بسرّ الويب هوك الخاص بك.
• X-Mistket-Delivery — معرّف الإرسال للتسجيل.

1. اقرأ جسم الطلب الخام — قبل تحليل JSON، لأن إعادة الترميز تغيّر البايتات.
2. أعد حساب HMAC — على الطابع الزمني ونقطة والجسم الخام بسرّ الويب هوك.
3. قارن في زمن ثابت — باستخدام hash_equals أو hmac.compare_digest أو crypto.timingSafeEqual.
4. ارفض الطوابع القديمة — مثل ما يزيد على خمس دقائق، لمنع إعادة الإرسال الخبيثة.
5. بعدها فقط حلّل ونفّذ — وأعد استجابة 2xx بسرعة.

يتبع هذا البناء نمط HMAC القياسي؛ أبقِ السر على الخادم وغيّره إن تسرّب.

اختيار رابط الاستدعاء وحمايته

استخدم مسار HTTPS مخصصًا مثل /webhooks/mistket منفصلًا عن صفحاتك العادية، ومرّره كرابط استدعاء عند إنشاء كل فاتورة. استثنِه من حماية CSRF والتخزين المؤقت وإعادة التوجيه؛ فإعادة توجيه 301 أو استجابة مخزنة سبب شائع لفشل الويب هوك بصمت. لا تشترط ملف تعريف ارتباط للجلسة؛ فالبوابة ليست مستخدمًا مسجلًا، والتوثيق هو توقيع HMAC. وأخيرًا سجّل كل إرسال مع الحدث ورقم الطلب ورمز الاستجابة لتجيب عن سؤال «هل وصل الويب هوك؟» في ثوانٍ.

عدم التأثر بالتكرار: قد يصل الحدث نفسه مرتين

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

• اعتمد رقم الطلب مفتاحًا — ابحث عن الطلب الذي تشير إليه الفاتورة.
• تحقق من الحالة الحالية — إن كان الطلب منفذًا بالفعل، فأكّد الاستلام ولا تفعل شيئًا آخر.
• استخدم معاملة أو قفلًا — كي لا يسلّم إرسالان متوازيان المنتج مرتين.
• خزّن معرّف الإرسال — مفيد لتتبع التكرارات.

تصميم حالات الطلب حول الأحداث

آلة حالات بسيطة تمنع معظم الأخطاء: معلّق ← قيد التأكيد (عند paid) ← مدفوع (عند confirmed) ← منفّذ، مع فروع لـ ناقص ومنتهٍ. اسمح بالانتقالات إلى الأمام فقط؛ فحدث invoice.paid الذي يصل بعد invoice.confirmed يجب ألا يعيد الطلب إلى الخلف. والدفعات المتأخرة لفواتير منتهية ينبغي أن تُنشئ سجلًا للمراجعة بدل إعادة فتح الطلب بصمت.

التعامل مع الحالات المزعجة

• الدفع الناقص — أخبر العميل بالمبلغ الناقص بالضبط وأنه يستطيع إرساله إلى صفحة الدفع نفسها؛ الدفعات الجزئية تُجمع.
• الدفع الزائد — نفّذ الطلب ثم قرر رصيدًا أو تحويل استرداد وفق سياستك.
• انتهاء الصلاحية — حرّر المخزون واعرض فاتورة جديدة إن ظل العميل راغبًا في الشراء.
• شبكة خاطئة — تُعالج عبر الدعم لا الشيفرة؛ اعرض الشبكة بوضوح في صفحة الدفع لتفاديها.

الاختبار والمراقبة

1. جهّز نقطة نهاية للاختبار — عبر HTTPS مع تسجيل الترويسات والأجسام الخام.
2. فعّل كل حدث — paid وconfirmed وunderpaid وoverpaid وexpired بمدفوعات حقيقية صغيرة.
3. أعد إرسال تسليم — تأكد أن المعالج يتجاهل التكرار.
4. أفسد التوقيع — غيّر بايتًا واحدًا وتأكد من رفض الطلب.
5. راقب سجلات الإرسال — تعرض لوحة التاجر كل محاولة ورمز استجابتها وتجزئة المعاملة.
6. نبّه عند الفشل — ارتفاع الاستجابات غير 2xx يعني طلبات لم تُنفَّذ.

تتبع الروبوتات والمجتمعات المدفوعة النمط نفسه؛ شاهد كيف يناسب ذلك تدفق المحادثة في قبول المدفوعات الرقمية في روبوت Telegram.

الويب هوك مع mistKET

ترسل mistKET ويب هوك موقّعًا بـ HMAC لكل حالة فاتورة، وتعيد محاولة الإرسالات الفاشلة بفواصل متزايدة، وتعرض في لوحة التاجر سجلات الإرسال والمبالغ المتوقعة والمستلمة وتجزئات المعاملات. وتُوقَّع طلبات API بالطريقة نفسها، فتغطي دالة مساعدة واحدة الاتجاهين.

اطلع على أمثلة الطلبات والويب هوك في قسم المطورين، وراجع الأسعار، وأدر مفاتيحك من دخول التجار. للحصول على وصول، قدّم عبر Telegram على @mistnetwork.