إعداد نقطة نهاية
ضيف نقطة نهاية webhook في لوحة التحكم، اختار الأحداث اللي تهمك، واحفظ سر التوقيع على السيرفر بتاعك.
نقطة نهاية الـ webhook هي رابط على السيرفر بتاعك XPay بيعمله POST بأحداث JSON كل ما حاجة مهمة تحصل: جلسة دفع تكتمل، أو مبلغ يترد، أو عميل يتعمل. بتضيفها مرة واحدة في لوحة التحكم، تختار الأحداث اللي عايزها، وتنسخ سر التوقيع على السيرفر بتاعك علشان تتأكد من كل حمولة قبل ما تتصرّف بناءً عليها.
نقاط نهاية الـ webhook بتتدار من لوحة التحكم بس، مش عن طريق الـ API. ونفس الكلام على سر التوقيع.
اعمل كل اللي تحت ده من app.xpay.app.
افتح صفحة الـ Webhooks
في لوحة التحكم، افتح صفحة المطورين واضغط على تبويب Webhooks. القائمة بتعرض كل نقطة معمولة للوضع الحالي.
وضع الاختبار والحساب الفعلي بيحتفظوا بقوائم نقاط منفصلة. استخدم مفتاح اختبار / الحساب الفعلي في أسفل الشريط الجانبي علشان تبدّل بينهم. النقطة اللي اتعملت في وضع الاختبار مش موجودة في الحساب الفعلي، والعكس صحيح.
أنشئ نقطة نهاية
اضغط إضافة نقطة نهاية
في أعلى يمين تبويب الـ Webhooks. لو القائمة فاضية، نفس الإجراء بيظهر في الحالة الفاضية باسم إنشاء نقطة نهاية webhook.
بتفتح لوحة جانبية بحقلين مطلوبين: الرابط والأحداث.
اكتب رابط النقطة
اكتب رابط كامل في رابط نقطة النهاية. النموذج بيتحقق من الشكل، مش من إمكانية الوصول. لازم الرابط يكون واحد السيرفر بتاعك بيخدمه فعلًا.
شوية قواعد:
- حط البروتوكول (
https://...). النموذج بيرفض القيم اللي ما بتتحلّلش كروابط. - استخدم HTTPS في الإنتاج. الـ HTTP العادي مقبول في النموذج، بس اللي عايزه بعد ما تنشر هو رابط HTTPS يوصله بشهادة صالحة. الرابط
http://localhost:...تمام في وضع الاختبار وأنت بتبني (شوف التطوير المحلي للأنفاق). - نقطة واحدة لكل رابط. لو محتاج توزّع على نظامين، اعمل نقطتين بروابط مختلفة، أو خلّي معالِج واحد يحوّل.
اختار الأحداث اللي هتستمع لها
تحت حقل الرابط فيه اختر الأحداث للاستماع إليها. المختار متقسّم لقسمين:
- قسم الأحداث الموصى بيها في الأعلى، بيطلّع الأحداث عالية الأهمية اللي معظم عمليات الدمج بتشترك فيها الأول (اكتمال جلسة الدفع، ودورة حياة الاسترداد، ودورة حياة العميل).
- وقسم متقدم قابل للطي تحته بيضمّ الباقي، مجمّع حسب المورد.
اضغط أي مجموعة علشان توسّعها وتعلّم على أحداث منفردة. كل مجموعة فيها مربّع اختيار كل الأحداث خاص بيها لو عايز كل أحداث المجموعة دي مرة واحدة. نفس المورد ممكن يظهر في القسمين لما أحداثه بتتوزّع على الاتنين. جلسات الدفع مثلًا بتعرض checkout.session.completed تحت قسم الموصى بيها وباقي دورة حياتها تحت متقدم.
لازم تختار واحد على الأقل. مجموعة بداية شائعة:
checkout.session.completedلدورة حياة الجلسة اللي أنشأتها.refund.createdوrefund.failedعلشان تتتبّع عمليات الرد.customer.created،customer.updated،customer.deletedعلشان تخلّي جدول العملاء بتاعك متزامن.
ضيف charge.succeeded / charge.failed (تحت متقدم ← Charges) لو نموذج بياناتك محتاج يتفاعل على مستوى الـ charge. اشترك بس في الأحداث اللي المعالِج بتاعك بيقراها فعلًا. كل اشتراك بيكلّف تسليم، وميزانية إعادة محاولة، وتحقق توقيع على السيرفر بتاعك.
علشان القائمة الكاملة، شوف مرجع الأحداث.
اضغط إضافة نقطة نهاية علشان تحفظ
XPay بيعمل النقطة وبيطلّعلك على طول نافذة مفتاح توقيع Webhook فيها قيمة whsec_*.
انسخها دلوقتي. لوحة التحكم مش هتعرضها تاني. لو ضيّعتها، مسارك الوحيد هو إنك تحذف النقطة وتعمل واحدة جديدة.
احفظها على السيرفر اللي بيشغّل المعالِج بتاعك، عادةً كمتغيّر بيئة زي XPAY_WEBHOOK_SECRET بيتحمّل مرة واحدة عند الإقلاع. اضغط تم علشان تقفل النافذة وترجع للقائمة.
سر التوقيع
كل نقطة ليها سر whsec_* خاص بيها. XPay بيوقّع كل حدث يتسلّم لنقطتك بـ HMAC-SHA256 باستخدام السر ده، والمعالِج بتاعك بيستخدم نفس السر علشان يتأكد إن الحدث الجاي جاي من XPay فعلًا.
تلت قواعد:
- عمرك ما تحط السر في كود العميل. مكانه على السيرفر. السر المسرَّب بيخلّي أي حد يقدر يزوّر أحداث في المعالِج بتاعك.
- خلّي أسرار الاختبار والحساب الفعلي منفصلة. كل نقطة ليها سرها. ما تستخدمش نفس متغيّر البيئة للاتنين.
- تعامل مع السر على إنه غير قابل للقراءة. هو سلسلة عشوائية ببادئة
whsec_. ما تحلّلهوش، وما تقصّهوش.
لو شككت إن سر اتسرّب، احذف النقطة واعملها تاني. لوحة التحكم ما بتقدّمش إجراء لتدوير السر حاليًا.
نقاط وضع الاختبار والحساب الفعلي
الاختبار والحساب الفعلي بيئتين معزولتين، كل واحدة ببياناتها ونقاط الـ webhook بتاعتها. مفتاح الوضع بيقرّر القائمة اللي لوحة التحكم بتعرضها؛ وبادئة مفتاح الـ API (sk_test_* مقابل sk_live_*) بتقرّر القائمة اللي الأحداث بتطلق عليها.
عادةً هتحتاج نقطتين على الأقل:
- نقطة اختبار بتشاور على نفق لجهاز التطوير بتاعك، أو على سيرفر تجريبي (staging).
- نقطة للحساب الفعلي بتشاور على الرابط اللي سيرفر الإنتاج بتاعك بيخدمه فعلًا.
كل واحدة بتاخد سر توقيع خاص بيها. ابنِ وتحقق على نقطة الاختبار الأول، وبعدين ضيف نقطة الحساب الفعلي قبل ما تحوّل حسابك للحساب الفعلي على طول.
أدِر نقاطك
قائمة الإجراءات على كل صف (زرّ الـ ⋮ على اليمين) فيها تلت اختيارات.
| الإجراء | بيعمل إيه |
|---|---|
| تعديل webhook | غيّر الرابط، أو الأحداث المشترَك فيها، أو الاتنين. سر التوقيع بيفضل زي ما هو، فكود التحقق بتاعك بيكمّل شغّال. |
| تعطيل webhook / تفعيل webhook | بطّل أو استأنف التسليمات من غير ما تفقد الإعدادات. مفيد وأنت بتنقّح معالِج. |
| حذف webhook | بيشيل النقطة نهائيًا. سر التوقيع بيبقى غير صالح. والتسليمات المعلّقة للنقطة دي بتقف. |
النقاط المعطّلة بتفضل في القائمة بشارة معطل. ما بتستقبلش أحداث وما بتعملش محاولات إعادة وهي معطّلة. وإعادة تفعيلها بتستأنف التسليمات الجديدة؛ الأحداث اللي اتطلقت وقت التعطيل مش بتترجع.
رايح فين بعد كده
التحقق من التوقيعات
اتأكد إن كل حدث جاي من XPay قبل ما تثق فيه. HMAC-SHA256 بحماية من إعادة الإرسال، في Node وPython.
إعادة الإرسال والمحاولات
جدول إعادة المحاولة لما المعالِج بتاعك يرجع غير 2xx، وإزاي تعيد إرسال حدث يدويًا من لوحة التحكم.
التطوير المحلي
حوّل تسليمات الـ webhook لجهازك وأنت بتبني المعالِج.
مرجع الأحداث
كل حدث تقدر تشترك فيه، إمتى بيتطلق، والكائن اللي بيحمله.
نموذج الكائنات
إيه اللي بيحتويه data.object بتاع كل حدث، وأنهي معرّفات تحتفظ بيها في سجل الطلب بتاعك.
وضع الاختبار وبطاقات الاختبار
شغّل دفعات اختبار حقيقية عبر نقطتك قبل ما تنتقل للحساب الفعلي.