كيف يعمل
1
تسجيل نقطة نهاية
أضف نقطة نهاية لخطاف الويب في الإعدادات > خطافات الويب في وحدة تحكم المستأجر. قم بتوفير عنوان URL HTTPS يمكن الوصول إليه علنًا واختر أنواع الأحداث التي ترغب في تلقيها.
2
تلقي الأحداث
عند حدوث حدث مطابق، يرسل Truthlocks طلب HTTP POST إلى عنوان URL الخاص بك مع حمولة JSON تصف الحدث.
3
التحقق من التوقيع
يتضمن كل طلب توقيع HMAC-SHA256 في رأس
X-Truthlocks-Signature. تحقق منه باستخدام سر نقطة النهاية لتأكيد أن الطلب جاء من Truthlocks.4
الاستجابة بـ 200
أرجع رمز حالة HTTP
200 للإقرار بالاستلام. إذا فشل نقطة النهاية الخاصة بك أو انتهت مهلتها، فإن Truthlocks تعيد المحاولة مع تراجع أسي.أنواع الأحداث
يتم تجميع الأحداث في فئات. يمكنك الاشتراك في أحداث فردية أو استخدام حرف بدل (attestation.*) لتلقي جميع الأحداث في فئة.
فلاتر الأحرف البديلة
استخدمcategory.* للاشتراك في كل حدث في فئة. على سبيل المثال، attestation.* يطابق attestation.created وattestation.revoked وattestation.expired وattestation.superseded.
حدود نقطة النهاية حسب الخطة
يعتمد عدد نقاط نهاية الويب هوك التي يمكنك إنشاؤها على مستوى خطتك:
هل تحتاج إلى المزيد من نقاط النهاية؟ اتصل بمدير حسابك أو قم بترقية خطتك في الإعدادات > الفواتير.
إنشاء نقطة نهاية
- في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks.
- انقر على إضافة نقطة نهاية.
- أدخل اسمًا، وعنوان URL لوجهة HTTPS الخاص بك، وحدد أنواع الأحداث التي ترغب في تلقيها.
- انقر فوق إنشاء.
عبر واجهة برمجة التطبيقات
Request
Response
نقاط نهاية القائمة
استرداد جميع نقاط نهاية webhook لمستأجرك:Request
التحقق من التوقيعات
يتضمن كل طلب ويب هوك رأس توقيع للتحقق. تحقق دائمًا من التوقيعات قبل معالجة الأحداث. تنسيق التوقيع:t هو الطابع الزمني لـ Unix و v1 هو ملخص HMAC-SHA256 السداسي العشري.
خطوات التحقق:
- استخرج
t(الطابع الزمني) وv1(التوقيع) من الرأس. - ارفض الطلب إذا كان الطابع الزمني أقدم من 5 دقائق.
- قم بدمج
{timestamp}.{raw_request_body}لتشكيل سلسلة التوقيع. - احسب HMAC-SHA256 لسلسلة التوقيع باستخدام سر نقطة النهاية الخاصة بك.
- قارن الملخص المحسوب بـ
v1باستخدام مقارنة ثابتة الوقت.
رؤوس الطلب
يتضمن كل تسليم ويب هوك هذه الرؤوس:سلوك إعادة المحاولة
إذا أعادت نقطة النهاية الخاصة بك رمز حالة غير 2xx أو لم تستجب في غضون 5 ثوانٍ، فإن Truthlocks تعيد محاولة التسليم مع تراجع أسي:
تشمل التأخيرات ما يصل إلى 30% من التذبذب. بعد 8 محاولات إجمالية (محاولة أولية واحدة + 7 محاولات إعادة)، يتم وضع علامة على التسليم على أنه فاشل.
يمكنك عرض محاولات التسليم وتفاصيل الفشل في الإعدادات > Webhooks بالنقر على نقطة نهاية، أو الاستعلام عنها عبر واجهة برمجة التطبيقات:
Request
تدوير الأسرار
إذا تم اختراق سر webhook الخاص بك، فقم بتدويره على الفور:- في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks وانقر على نقطة النهاية.
- انقر على تدوير السر.
- انسخ السر الجديد — يتوقف السر القديم عن العمل فورًا.
Request
اختبار خطافات الويب (webhooks)
أرسل حدث اختبار للتحقق من أن نقطة النهاية تعمل:- في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks وانقر على نقطة النهاية.
- انقر على إرسال اختبار.
- يتم إرسال حدث
webhook.testإلى عنوان URL الخاص بك باستخدام مسار التوقيع والتسليم الكامل.
Request
event_type وpayload اختياريان - يتم تعيينهما افتراضيًا إلى webhook.test وحمولة حالة أساسية إذا تم حذفهما.
إشعارات إشارة المخاطر
يمكنك تلقي إشعارات الويب هوك في الوقت الفعلي كلما تم إنشاء إشارة مخاطر بواسطة أي من مسارات الكشف الخمسة جدار حماية هوية مكافحة الاحتيال — الاستيعاب المباشر، وتطبيع الأحداث، ومسح التزييف العميق، واكتشاف ATO، وتسجيل السرعة. اشترك فيrisk.signal.* لتلقي جميع أحداث إشارة المخاطر، أو اشترك في risk.signal.created أو risk.signal.escalated بشكل فردي.
حمولة مثال
الاستجابة لإشارات المخاطر
استخدم خطافات الويب لإشارة المخاطر لتشغيل استجابات تلقائية — حظر جلسة مستخدم، أو إخطار فريق الأمان الخاص بك، أو التصعيد إلى حالة احتيال — دون استقصاء واجهة برمجة التطبيقات.تطلق webhooks إشارة المخاطر للإشارات التي تم إنشاؤها بواسطة جميع مسارات الكشف الخمسة. يخبرك حقل
signal_source في الحمولة بالمسار الذي أنشأ الإشارة — external، event_normalization، deepfake، ato، أو velocity.أفضل الممارسات
- تحقق من كل توقيع. لا تتخطى أبدًا التحقق من التوقيع، حتى في مرحلة التطوير.
- استخدم قائمة انتظار الرسائل. قم بوضع الأحداث الواردة في قائمة الانتظار ومعالجتها في عامل لتجنب حظر استجابة HTTP.
- التعامل مع التكرارات. استخدم رأس
X-Truthlocks-Event-Idلإزالة تكرار الأحداث في حالة إعادة المحاولة. - مراقبة حالات فشل التسليم. تحقق من علامة تبويب التسليمات في وحدة التحكم بانتظام بحثًا عن التسليمات الفاشلة أو المعطلة.
- حافظ على سرية الأسرار. قم بتخزين سر webhook الخاص بك في متغيرات البيئة، وليس في الكود المصدري.

