Webhooks المدفوعات
كيف يستقبل HyoNova Webhooks مزوّدي الدفع — الجسم الخام، والتحقق من التوقيع، ومنع التكرار، والترتيب، والمعالجة الذرية، وأي ردود HTTP تجعل المزوّد يعيد المحاولة.
لا تظهر طريقة الدفع إلا بعد أن يُعدّ HyoNova مزوّد الدفع الخاص بها.
يُبلغ مزوّدو الدفع HyoNova بالمدفوعات والاشتراكات باستدعاء Webhook. وهذه الـWebhooks — لا عودة المتصفح من صفحة الدفع — هي ما يغيّر اشتراك الشركة. تصف هذه الصفحة جانب الاستقبال. (أما الـWebhooks التي يرسلها هيو ميل إلى أنظمتك أنت فراجع Webhooks.)
نقطة الاستقبال#
POST https://<HyoNova product API host>/api/v1/webhooks/payments/<provider><provider> هو مسار Webhook المزوّد: fastspring أو triple-a أو stripe. وليس للتحويل البنكي Webhook. ويعرض مركز التحكم العنوان الدقيق على كل نسخة مزوّد. والمسارات غير المعروفة تُرد بـ404، والجسم الفارغ بـ400. والجسم محدود بـ512 كيلوبايت، ونقطة الاستقبال محدودة المعدّل.
المعالجة خطوة بخطوة#
- الجسم الخام. يُقرأ الجسم بايتات خاماً لأن التوقيع يغطي البايتات نفسها تماماً. ولا يحدث أي تحليل JSON قبل التحقق.
- التوقيع. يجرّب HyoNova كل نسخة من نسخ ذلك المزوّد (يمكن أن تتعايش نسختا الاختبار والإنتاج) بسرّ توقيعها، بمقارنة ثابتة الزمن. وإن لم تتطابق أي نسخة ← 401
WEBHOOK_SIGNATURE_INVALIDولا يُخزَّن شيء. - التوحيد. يحوّل المحوّل الحمولة إلى أحداث موحّدة مستقلة عن المزوّد. وقد ينتج الإشعار الواحد عدة أحداث.
- منع التكرار. يُسجَّل كل حدث بمفتاحه (المزوّد، معرّف الحدث). والمفتاح الذي عولج سابقاً
duplicateولا يغيّر شيئاً. - فحص البيئة. الحدث التجريبي لا يغيّر أبداً بيانات نسخة حقيقية، والعكس كذلك.
- مطابقة الشركة من مراجع خزّنها HyoNova بنفسه (عملية الدفع أو الاشتراك أو الدفعة أو الطلب أو الفاتورة أو عميل المزوّد). ولا يُوثق بالمعرّفات التي يعيدها المزوّد إلا حين تطابق سجلاً مخزّناً.
- الترتيب. الحدث الأقدم من آخر حدث طُبّق على الاشتراك — برقم تسلسل المزوّد حين يتوفر، وإلا بالوقت — يُتجاهل ولا يُرجع الاشتراك إلى الوراء أبداً.
- التطبيق الذري. يُثبَّت التغيير ومدخل السجل الزمني لفوترة الشركة وحدث الـoutbox للإشعارات ومدخل التدقيق معاً في معاملة واحدة.
التواقيع#
| المزوّد | الترويسة | المحتوى الموقّع |
|---|---|---|
| FastSpring | X-FS-Signature | HMAC-SHA256 بترميز Base64 للجسم الخام بسرّ HMAC الخاص بالـWebhook |
| Triple-A | Triplea-Signature: t=<unix>,v1=<hex> | HMAC-SHA256 لـ <t>.<raw body> بسرّ الإشعارات؛ سماحية 300 ثانية |
| Stripe | Stripe-Signature: t=<unix>,v1=<hex> | HMAC-SHA256 لـ <t>.<raw body> بسرّ نقطة الاستقبال؛ سماحية 300 ثانية |
ردود HTTP#
| الرد | متى | سلوك المزوّد |
|---|---|---|
| 200 | عولج كل حدث أو تُجوهل أو كان مكرراً. ويذكر الجسم معرّفات الأحداث المعالجة | انتهى |
| 401 | لم تتحقق أي نسخة من التوقيع | لا يُخزَّن شيء؛ أصلح السر |
500 PROCESSING_FAILED | فشل حدث واحد على الأقل، ويُخزَّن فاشلاً مع خطأ آمن | يعيد المزوّد المحاولة؛ تُمنع إعادة الأحداث المعالجة ويُعاد تشغيل الفاشل |
| 404 / 400 | مسار مزوّد غير معروف / جسم فارغ | — |
ملاحظات أمنية#
- لا توجد جلسة أو ملف تعريف ارتباط. ويُتجاوز فحص CSRF لنمط هذا المسار تحديداً فقط؛ والتوقيع هو المصادقة.
- تُقرأ الأسرار من مخزن الأسرار للتحقق فقط، ولا تُسجَّل أبداً.
- الأحداث التي تبقى فاشلة تظهر في المطابقة في مركز التحكم عناصرَ تحتاج انتباهاً.
هل كانت هذه الصفحة مفيدة؟
شكراً. لا تُجمع تقييمات الصفحات بعد، لذلك لم يُرسَل شيء. إذا وجدت نقصاً أو خطأً فراجع صفحة «الحصول على المساعدة».