كيفية إعداد Webhooks في OxaPay: دليل عملي

إكمال العميل عملية دفع بالعملات المشفرة ليس سوى بداية سير عمل الدفع. فما يزال على موقعك أو تطبيقك تأكيد النتيجة، وتحديث الطلب الصحيح، وإبلاغ العميل، وتحديد ما إذا كان تنفيذ الطلب يمكن أن يبدأ. وتتيح Webhooks من OxaPay ذلك عبر إرسال تحديثات حالة الدفع مباشرة إلى خادمك.

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

ما وظيفة Webhook في OxaPay؟

Webhook رسالة تُرسل من خادم إلى آخر عند وقوع حدث. وبدلاً من أن يستعلم نظامك باستمرار عما إذا كانت حالة الدفع قد تغيرت، ترسل OxaPay استدعاءً راجعًا بصيغة JSON إلى عنوان HTTPS الذي تحدده عند توفر معلومات جديدة عن الدفع.

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

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

متى تحتاج شركتك إلى Webhook للمدفوعات؟

يكون Webhook المخصص أكثر فائدة عندما يتعين أن تؤدي نتيجة الدفع إلى إجراء آخر تلقائيًا. وتشمل الأمثلة الشائعة ما يلي:

• نقل طلب متجر إلكتروني من حالة الانتظار إلى الجاهزية للتنفيذ؛
• تفعيل حساب SaaS أو تمديد اشتراك؛
• إرسال تأكيد دفع عبر البريد الإلكتروني أو الرسائل النصية أو رسالة داخل التطبيق؛
• تحديث المخزون أو نظام CRM أو المحاسبة أو أنظمة التقارير الداخلية؛
• تنبيه فريق العمليات عندما يكون الدفع  أقل من المبلغ المطلوب أو منتهي الصلاحية، أو يستدعي المراجعة لسبب آخر.

إذا كنت تستخدم إضافة دفعمدعومة، فقد يتولى التكامل بالفعل جزءًا كبيرًا من هذا المنطق. وإذا كنت تنشئ  Payment Links and review them manually, you may not need a custom endpoint. تكاملات API المباشرة and custom platforms usually benefit the most.

كيف يعمل تدفق Webhook في OxaPay؟

1. Your system creates or identifies a payment and stores OxaPay’s track_id with your own order or customer reference.
2. يرسل العميل الدفعة وتتغير حالتها أثناء معالجتها لدى OxaPay.
3. ترسل OxaPay استدعاءً راجعًا موقّعًا بصيغة JSON إلى عنوان URL الذي أعددته للاستدعاء.
4. يتحقق خادمك من التوقيع قبل الوثوق بالرسالة.
5. يربط خادمك الاستدعاء بالسجل الصحيح ويتحقق من بيانات الدفع المهمة.
6. يسجل تطبيقك الحدث، وينفذ كل إجراء تجاري معتمد مرة واحدة فقط، ويعيد استجابة HTTP ناجحة.

هذا الفصل مهم؛ إذ ينقل Webhook تحديث الدفع، لكن تطبيقك يظل مسؤولًا عن تحديد ما يعنيه ذلك التحديث للطلب أو الحساب أو الشحنة أو القيد المحاسبي.

قبل البدء

جهّز ما يلي قبل ربط الاستدعاء الراجع:

• نقطة نهاية HTTPS متاحة للوصول العام وتقبل طلبات HTTP POST؛
• وصولًا من جانب الخادم إلى بيانات اعتماد تاجر OxaPay المعنية، مع تخزينها بأمان وعدم كشفها مطلقًا في شيفرة المتصفح؛
• سجلًا في قاعدة البيانات يربط معرّف OxaPay  track_id with your own order, invoice, or user ID;
• قواعد واضحة تحدد حالات الدفع التي يمكنها تفعيل تنفيذ الطلب، أو منح الوصول، أو رد الأموال، أو إرسال الإشعارات، أو المراجعة اليدوية؛
• تسجيلًا للأحداث ومراقبةً تكشف إخفاقات التسليم، وأخطاء التحقق، والتغييرات غير المتوقعة في الحالة.

إذا كنت تخطط لتكامل أوسع، فاستخدم  قائمة التحقق من تكامل مدفوعات العملات المشفرة to review keys, payment methods, callbacks, testing, and go-live controls together.

كيفية إعداد Webhooks في OxaPay

حدّد قواعد حالات الدفع

قرر ما الذي ينبغي لشركتك فعله في كل  حالة دفع before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.

اسمح فقط بانتقالات الحالة الموثقة والمتوقعة. فعلى سبيل المثال، لا ينبغي تنفيذ طلب نُفذ بالفعل مرة أخرى لمجرد تسليم الاستدعاء ذاته مرتين.

أنشئ نقطة نهاية آمنة للاستدعاء الراجع

أنشئ مسار HTTPS مخصصًا في الواجهة الخلفية، مثل  https://example.com/webhooks/oxapay. يجب أن يقبل طلبات POST، ويحتفظ بإمكانية الوصول إلى متن الطلب الخام للتحقق من التوقيع، ويرفض الطرق غير المدعومة أو الطلبات غير السليمة.

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

زوّد OxaPay بعنوان URL للاستدعاء الراجع

أضف عنوان الاستدعاء الراجع إلى تدفق الدفع المعني في OxaPay. وبحسب المنتج أو طريقة التكامل، قد يُقدَّم العنوان ضمن طلب الدفع أو في إعدادات التاجر المعمول بها. ارجع إلى  توثيق OxaPay Webhook for the exact field and behavior of the service you are implementing.

استخدم عنوان URL نفسه باستمرار داخل كل بيئة. وافصل نقاط النهاية التجريبية عن نقاط الإنتاج حتى لا تتمكن أحداث الاختبار من تعديل الطلبات الفعلية.

تحقق من التوقيع قبل الوثوق بالاستدعاء

توثق OxaPay توقيع HMAC-SHA512 يُنشأ من بيانات POST الخام باستخدام مفتاح API الخاص بالتاجر بوصفه السر المشترك. وينبغي أن يحسب خادمك التوقيع المتوقع من متن الطلب الخام دون تغيير، ثم يقارنه بالتوقيع المرفق بالاستدعاء.

ارفض الطلب إذا فشل التحقق. استخدم مقارنة ذات زمن ثابت متى كان إطار العمل يدعمها، ولا تسجل مطلقًا مفتاح API الخاص بالتاجر أو أي أسرار أخرى. فقد يؤدي تحليل JSON ثم إعادة تسلسله قبل حساب HMAC إلى تغيير المسافات أو ترتيب الحقول، ما يتسبب في فشل التحقق من توقيع صحيح.  مرجع التحقق من الاستدعاءات explains the broader security model.

طابق الدفعة وتحقق من بياناتها

يؤكد التوقيع الصحيح مصدر الرسالة، لكن على تطبيقك أيضًا التحقق من بيانات الأعمال. طابق المعرّف  track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.

لا تسمح لدفعة غير معروفة أو مبلغ غير متوقع أو انتقال حالة غير صحيح بتفعيل تنفيذ الطلب تلقائيًا. سجل الحدث للتحقيق وتأكد من معلومات الدفع الحالية عبر API.

عالج كل حدث بطريقة تمنع تكرار الأثر

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

تجعل خاصية عدم تكرار الأثر التسليم المكرر مجرد إعادة محاولة غير ضارة، بدلًا من شحنة مكررة أو تمديد اشتراك متكرر أو قيد محاسبي مزدوج.

سجّل الحدث واستجب بسرعة

بعد اجتياز الطلب عملية التحقق، احفظ الاستدعاء ونتيجة التحقق منه قبل إعادة HTTP  200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.

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

اختبار دورة حياة الدفع كاملةً

لا تكتفِ باختبار استدعاء ناجح. غطِّ تأخر الدفع ونقص المبلغ وانتهاء الصلاحية وتكرار التسليم والتوقيعات غير الصالحة وقيم  track_id values, temporary database failure, and recovery after downtime.

تحقق من النتيجة التقنية ونتيجة الأعمال معًا. فقد تعيد نقطة النهاية  200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.

استخدم Webhooks مع استعلامات الحالة

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

For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.

حالات استخدام عملية لـ Webhook

طلبات التجارة الإلكترونية

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

SaaS والوصول الرقمي

فعّل الحساب أو مدّد الوصول فقط بعد التحقق من نتيجة الدفع. وسجّل فترة الدفع أو تغيير الصلاحية حتى لا يمنح الاستدعاء المكرر الميزة نفسها مرتين.

المالية والمطابقة

أضف أحداث الدفع إلى سجل التدقيق واربطها بالفاتورة الداخلية. ويمكن إحالة الحالات الاستثنائية إلى طابور للمراجعة، بينما تتولى استعلامات الحالة المجدولة مطابقة المدفوعات التي لم تُحسم بعد.

التواصل مع العملاء

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

أخطاء Webhook الشائعة

• الثقة بصفحة العودة: use verified server-side payment information instead of a browser redirect.
• التحقق من JSON بعد إعادة تنسيقه: calculate the HMAC from the original raw request body.
• كشف مفتاح التاجر: keep signing credentials in protected server-side storage.
• افتراض أن كل استدعاء فريد: make every business action idempotent.
• تنفيذ الكثير قبل الرد: durably record the event, queue slow work, and respond promptly.
• قبول أي انتقال للحالة: enforce a controlled payment state model.
• الاعتماد على التسليم وحده: use payment information requests for recovery and reconciliation.
• تسجيل بيانات حساسة: retain useful identifiers and validation results without storing secrets unnecessarily.

استكشاف مشكلات Webhook في OxaPay وإصلاحها

قائمة التحقق قبل تشغيل Webhooks في OxaPay فعليًا

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

ما الخطوة التالية؟

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

للتعمق في حالات الدفع والتسليم وبنية التعافي، اقرأ  المراقبة في الوقت الفعلي في أنظمة الدفع القائمة على البلوكشين. ويجب أن يعتمد المطورون على  وثائق OxaPay الحالية الخاصة بـ Webhook as the implementation source of truth.