نظرة عامة على الويب هوك
ترسل أوكتين طلب POST موقّعًا عبر HTTPS إلى نقطة النهاية لديك عند تأكيد معاملة أو تسجيل معاملة خارجية. متطلبات نقطة النهاية وأنواع الأحداث.
يتيح الويب هوك لأوكتين إخطار نظامك شبه فوريًا بدلًا من استطلاع واجهة السحب. كلما تم تأكيد إحدى معاملاتك أو تسجيل معاملة خارجية، ترسل أوكتين طلب POST عبر HTTPS إلى نقطة النهاية لديك مع سجل المعاملة الكامل.
كيف يعمل الويب هوك؟
- تعطي أوكتين عنوان HTTPS عند إنشاء مفتاح API (أو لاحقًا عند الطلب). تولّد أوكتين سر الويب هوك وتشاركه معك مرة واحدة.
- عندما تصل معاملة إلى حالة
CONFIRMEDأوEXTERNAL، تبني أوكتين الحمولة وترسلها بـPOSTإلى عنوانك موقّعة بالسر. - تتحقق نقطة النهاية لديك من التوقيع وترد بأي حالة
2xxخلال 500 ملّي ثانية. - إذا فشل التسليم، تعيد أوكتين المحاولة حتى 3 مرات. تُسجَّل حالات الفشل المستمر، وبعد فشل مطوّل يُعطَّل الويب هوك وتُخطَر بالبريد الإلكتروني.
تغذية بالمعاملات الجديدة، لا مرآة لدورة الحياة
يُطلق الويب هوك مرة واحدة لكل معاملة، عندما تصبح CONFIRMED أو EXTERNAL. لا تُرسل التغييرات اللاحقة (إلغاء أو إبطال). استخدم واجهة السحب لاكتشافها. راجع أفضل الممارسات.
متطلبات نقطة النهاية
| المتطلب | التفصيل |
|---|---|
| البروتوكول والمنفذ | https:// على المنفذ 443 فقط. يُرفض HTTP العادي والمنافذ غير القياسية. |
| إمكانية الوصول | يجب أن يُحلّ اسم المضيف إلى عنوان IP عام. تُرفض النطاقات الخاصة والمحلية ونطاقات الربط المحلي وبيانات السحابة الوصفية. |
| TLS | شهادة صالحة وموثوقة علنًا. |
| إعادة التوجيه | لا تُتبع. يجب أن يرد العنوان مباشرة. |
| المهلة | الرد خلال 500 ملّي ثانية، محسوبة من الاتصال حتى اكتمال الاستجابة. أعد 2xx فورًا ثم عالج الحدث بشكل غير متزامن. الرد البطيء يُحسب تسليمًا فاشلًا. |
| النجاح | أي حالة 2xx. يُتجاهل جسم الاستجابة. |
يُضبط عنوان ويب هوك واحد لكل مفتاح API. إن احتجت إلى عدة وجهات، اطلب من أوكتين مفتاحًا لكل وجهة.
ما الذي يُطلق الويب هوك؟
| الحدث | يُرسل عندما |
|---|---|
transaction.confirmed | تصبح المعاملة CONFIRMED، بما فيها معاملات الاسترداد للتكرار والفروق والنزاعات المحلولة. |
transaction.external | تُسجَّل معاملة EXTERNAL (محطة خارج شبكة أوكتين). |
webhook.test | عند الطلب، للتحقق من نقطة النهاية لديك. |
لا يُرسل: معاملات PENDING أو VOID أو CANCELED، أو تغييرات الحالة اللاحقة لمعاملة سُلّمت بالفعل، أو تسويات الرصيد اليدوية.
لا تُرسل سوى المعاملات المنشأة بعد ضبط عنوان الويب هوك. استخدم واجهة السحب لجلب ما قبل ذلك.