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

كيف يعمل

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.

حدود نقطة النهاية حسب الخطة

يعتمد عدد نقاط نهاية الويب هوك التي يمكنك إنشاؤها على مستوى خطتك: هل تحتاج إلى المزيد من نقاط النهاية؟ اتصل بمدير حسابك أو قم بترقية خطتك في الإعدادات > الفواتير.

إنشاء نقطة نهاية

  1. في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks.
  2. انقر على إضافة نقطة نهاية.
  3. أدخل اسمًا، وعنوان URL لوجهة HTTPS الخاص بك، وحدد أنواع الأحداث التي ترغب في تلقيها.
  4. انقر فوق إنشاء.
تعرض وحدة التحكم سر نقطة النهاية الخاص بك مرة واحدة. انسخه فورًا — لا يمكنك استعادته لاحقًا.

عبر واجهة برمجة التطبيقات

Request
Response

نقاط نهاية القائمة

استرداد جميع نقاط نهاية webhook لمستأجرك:
Request
راجع مرجع API الكامل للحصول على تفاصيل الاستجابة.

التحقق من التوقيعات

يتضمن كل طلب ويب هوك رأس توقيع للتحقق. تحقق دائمًا من التوقيعات قبل معالجة الأحداث. تنسيق التوقيع:
حيث t هو الطابع الزمني لـ Unix و v1 هو ملخص HMAC-SHA256 السداسي العشري. خطوات التحقق:
  1. استخرج t (الطابع الزمني) و v1 (التوقيع) من الرأس.
  2. ارفض الطلب إذا كان الطابع الزمني أقدم من 5 دقائق.
  3. قم بدمج {timestamp}.{raw_request_body} لتشكيل سلسلة التوقيع.
  4. احسب HMAC-SHA256 لسلسلة التوقيع باستخدام سر نقطة النهاية الخاصة بك.
  5. قارن الملخص المحسوب بـ v1 باستخدام مقارنة ثابتة الوقت.
استخدم دائمًا دالة مقارنة ثابتة الوقت (مثل crypto.timingSafeEqual أو hmac.compare_digest) لمنع هجمات التوقيت.

رؤوس الطلب

يتضمن كل تسليم ويب هوك هذه الرؤوس:

سلوك إعادة المحاولة

إذا أعادت نقطة النهاية الخاصة بك رمز حالة غير 2xx أو لم تستجب في غضون 5 ثوانٍ، فإن Truthlocks تعيد محاولة التسليم مع تراجع أسي: تشمل التأخيرات ما يصل إلى 30% من التذبذب. بعد 8 محاولات إجمالية (محاولة أولية واحدة + 7 محاولات إعادة)، يتم وضع علامة على التسليم على أنه فاشل. يمكنك عرض محاولات التسليم وتفاصيل الفشل في الإعدادات > Webhooks بالنقر على نقطة نهاية، أو الاستعلام عنها عبر واجهة برمجة التطبيقات:
Request
راجع مرجع API لتسليم القوائم للحصول على تفاصيل الاستجابة.

تدوير الأسرار

إذا تم اختراق سر webhook الخاص بك، فقم بتدويره على الفور:
  1. في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks وانقر على نقطة النهاية.
  2. انقر على تدوير السر.
  3. انسخ السر الجديد — يتوقف السر القديم عن العمل فورًا.
يمكنك أيضًا التدوير عبر واجهة برمجة التطبيقات:
Request

اختبار خطافات الويب (webhooks)

أرسل حدث اختبار للتحقق من أن نقطة النهاية تعمل:
  1. في لوحة تحكم المستأجر، انتقل إلى الإعدادات > Webhooks وانقر على نقطة النهاية.
  2. انقر على إرسال اختبار.
  3. يتم إرسال حدث 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.

أفضل الممارسات

استجب لـ webhooks بسرعة. قم بمعالجة البيانات الثقيلة بشكل غير متزامن بعد إرجاع استجابة 200 لتجنب المهلات وإعادة المحاولات.
  • تحقق من كل توقيع. لا تتخطى أبدًا التحقق من التوقيع، حتى في مرحلة التطوير.
  • استخدم قائمة انتظار الرسائل. قم بوضع الأحداث الواردة في قائمة الانتظار ومعالجتها في عامل لتجنب حظر استجابة HTTP.
  • التعامل مع التكرارات. استخدم رأس X-Truthlocks-Event-Id لإزالة تكرار الأحداث في حالة إعادة المحاولة.
  • مراقبة حالات فشل التسليم. تحقق من علامة تبويب التسليمات في وحدة التحكم بانتظام بحثًا عن التسليمات الفاشلة أو المعطلة.
  • حافظ على سرية الأسرار. قم بتخزين سر webhook الخاص بك في متغيرات البيئة، وليس في الكود المصدري.