الانتقال إلى المحتوى الرئيسي
POST
curl
تتيح لك وجهات webhook إرسال أحداث Didit المختلفة إلى عناوين URL مختلفة. لكل وجهة secret_shared_key وwebhook_version وقائمة subscribed_events خاصة بها.

كيف يعمل subscribed_events

subscribed_events مصفوفة مطلوبة تحتوي على أسماء أحداث مطابقة تمامًا. لا يرسل Didit webhook إلى هذه الوجهة إلا عندما تطابق قيمة webhook_type في payload واحدة من القيم الموجودة في المصفوفة.
  • أضف حدثاً واحداً على الأقل.
  • استخدم أسماء الأحداث المدعومة الواردة أدناه فقط.
  • أضف كل حدث تريد تسليمه؛ لا توجد قيمة بديلة شاملة مثل * أو all.
  • لتوجيه مجالات المنتج المختلفة إلى أنظمة مختلفة، أنشئ وجهات متعددة بقوائم subscribed_events مختلفة.

كتالوج الأحداث

كما تُقبل عائلتا الأحداث investigator.* وauth.*. ترد كل الأحداث وpayload الخاصة بها في Webhooks. مجموعات الاشتراك الشائعة:
لأمثلة payload وكود التوقيع، راجع دليل webhooks.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json
label
string
مطلوب

اسم سهل القراءة يُعرض في Console ← Webhooks. يساعد في التمييز بين الوجهات عندما يكون لديك عدة وجهات (مثل "Prod"، "Staging mirror").

Maximum string length: 255
url
string<uri>
مطلوب

رابط HTTPS الذي سيتلقى طلبات POST. يجب أن يكون فريداً بين وجهات التطبيق. استخدم endpoint مستقراً ومؤمّناً: تعيد Didit محاولة عمليات التسليم الفاشلة وفق جدول زمني تصاعدي.

Maximum string length: 2000
enabled
boolean
افتراضي:true

عندما تكون القيمة false، يتم حفظ الوجهة ولكن Didit لن ترسل إليها أي webhooks. هذا مفيد لإعدادات بيئات الاختبار التي تريد إبقاءها معلقة مؤقتاً.

webhook_version
enum<string>

إصدار مخطط payload الذي سترسله Didit. الإصدار v3 هو التنسيق الحالي/الموصى به؛ ويتم الاحتفاظ بالإصدارات الأقدم للتوافق مع عمليات التكامل القديمة.

الخيارات المتاحة:
v1,
v2,
v3
subscribed_events
enum<string>[]

الأحداث المراد تسليمها. مطلوبة عملياً: يتم رفض [] الصريحة بالرمز 400، ويؤدي حذف الحقل إلى إنشاء وجهة بدون أي اشتراكات ولا تتلقى أي شيء.

Minimum array length: 1

اسم حدث webhook المدعوم. استخدم هذه النصوص بدقة في subscribed_events؛ حيث يتم رفض القيم غير المدعومة.

الخيارات المتاحة:
status.updated,
data.updated,
user.status.updated,
user.data.updated,
business.status.updated,
business.data.updated,
activity.created,
transaction.created,
transaction.status.updated,
travel_rule.status.updated,
workflow.compliance_changed,
transaction_rule_suggestions.created,
auth.signup,
auth.login,
auth.login_failed,
auth.password_reset_requested,
auth.password_reset_completed,
auth.mfa_changed,
auth.new_device,
auth.account_locked,
investigator.report.ready,
investigator.decision.automated,
investigator.decision.overridden,
investigator.decision.contested,
investigator.question.raised,
investigator.automation.paused,
investigator.rfi.answered,
investigator.rfi.overdue,
investigator.drift.detected,
investigator.sla.breached,
investigator.qa.failed,
investigator.external.report.ready
مثال:

الاستجابة

تم إنشاء الوجهة. secret_shared_key هو السر المشترك لتوقيع HMAC — خزّنه الآن.

uuid
string<uuid>

معرّف الوجهة الثابت. يُستخدم كـ {destination_uuid} في الاستدعاءات اللاحقة.

label
string
url
string<uri>
enabled
boolean
webhook_version
enum<string>
الخيارات المتاحة:
v1,
v2,
v3
secret_shared_key
string

سر توقيع HMAC يتم إنشاؤه تلقائياً ويكون مرتبطاً بهذه الوجهة (token آمن لعناوين URL بطول 43 حرفاً). استخدمه للتحقق من رؤوس التوقيع على webhooks الواردة. يتم إرجاعه دائماً بالكامل للمتصلين عبر مفتاح API؛ ويحتاج مستخدمو لوحة التحكم إلى إذن read:webhooks، وإلا فسيظهر لهم نص فارغ.

secret_last4
string

آخر أربعة أحرف من سر التوقيع الحالي للوجهة، لتتمكن من التمييز بين الأسرار. غير كافية للتحقق من التوقيع.

previous_secret_expires_at
string<date-time> | null

يُعيَّن لمدة 24 ساعة بعد تدوير سر التوقيع للوجهة في Business Console. حتى هذا الوقت، يحمل كل تسليم إلى الوجهة أيضاً X-Signature-Previous و X-Signature-V2-Previous و X-Signature-Simple-Previous، المنشأة باستخدام السر المُستبدل (انظر التحقق من التوقيع). تكون القيمة null في حال عدم حدوث أي تدوير خلال آخر 24 ساعة.

subscribed_events
enum<string>[]

أداة تصفية الأحداث لوجهة webhook هذه. تسلّم Didit فقط إشعارات webhook التي يتطابق نوع الحدث الخاص بها تماماً مع إحدى هذه القيم — لا يوجد اشتراك باستخدام أحرف البدل. عند الإرسال، يجب أن تحتوي القائمة على حدث صالح واحد على الأقل (يتم رفض [] الصريحة بالرمز 400)؛ والوجهة التي تكون قائمتها فارغة (تم إغفال الحقل عند الإنشاء) لا تتلقى أي شيء. عند التحديث، يتم استبدال القائمة بالكامل ولا تُدمج أبداً.

Minimum array length: 1

اسم حدث webhook المدعوم. استخدم هذه النصوص بدقة في subscribed_events؛ حيث يتم رفض القيم غير المدعومة.

الخيارات المتاحة:
status.updated,
data.updated,
user.status.updated,
user.data.updated,
business.status.updated,
business.data.updated,
activity.created,
transaction.created,
transaction.status.updated,
travel_rule.status.updated,
workflow.compliance_changed,
transaction_rule_suggestions.created,
auth.signup,
auth.login,
auth.login_failed,
auth.password_reset_requested,
auth.password_reset_completed,
auth.mfa_changed,
auth.new_device,
auth.account_locked,
investigator.report.ready,
investigator.decision.automated,
investigator.decision.overridden,
investigator.decision.contested,
investigator.question.raised,
investigator.automation.paused,
investigator.rfi.answered,
investigator.rfi.overdue,
investigator.drift.detected,
investigator.sla.breached,
investigator.qa.failed,
investigator.external.report.ready
مثال:
created_by_email
string | null

البريد الإلكتروني لعضو Business Console الذي أنشأ الوجهة. يكون null بالنسبة للوجهة التي تم إنشاؤها باستخدام مفتاح API.

created_by_name
string | null

اسم عضو Business Console الذي أنشأ الوجهة. null لوجهة تم إنشاؤها باستخدام مفتاح API.

created_at
string<date-time>
updated_at
string<date-time>
health_status
enum<string>

حالة التشغيل للتسليم. failing: فشل 3 أحداث متتالية أو أكثر في أول محاولة تسليم لها منذ آخر استجابة ناجحة للوجهة (راجع failing_streak). degraded: ليست في حالة failing، ولكن فشلت محاولة تسليم خلال آخر 24 ساعة ولم تنجح أي محاولة لاحقة في تسليم ذلك الحدث؛ وستؤدي إعادة المحاولة أو إعادة الإرسال التي تنجح في تسليمه إلى محو هذه الحالة. healthy: ليست في أي من الحالتين السابقتين. مستقلة عن enabled. المحاولة الفاشلة هي المحاولة التي تمت الاستجابة لها برمز HTTP 400 أو أعلى، أو لم تتم الاستجابة لها على الإطلاق.

الخيارات المتاحة:
healthy,
degraded,
failing
failing_streak
integer

عدد الأحداث المتتالية التي فشلت محاولة تسليمها الأولى منذ آخر استجابة ناجحة للوجهة، خلال آخر 30 يوماً. لا تُحتسب عمليات إعادة المحاولة، وأي محاولة ناجحة، بما في ذلك إعادة المحاولة أو إعادة الإرسال، تنهي سلسلة الفشل. تكون القيمة 0 عندما لا يفشل أي حدث منذ آخر نجاح.

failing_since
string<date-time> | null

وقت إجراء أول محاولة فاشلة في failing_streak الحالية. تكون القيمة null عندما تكون failing_streak تساوي 0.

last_success_at
string<date-time> | null

وقت آخر استجابة من الوجهة لتسليم بحالة HTTP أقل من 400، خلال آخر 30 يوماً. وتكون القيمة null إذا لم تُجب خلال تلك الفترة بتسليم ذي حالة HTTP أقل من 400.

environment
enum<string>

بيئة التطبيق الذي يملك الوجهة.

الخيارات المتاحة:
live,
sandbox
summary
object

مقاييس التسليم لآخر metrics_window_days (30) يوماً. last_delivery_at هي أحدث محاولة، بغض النظر عن وقت إجرائها.

آخر تعديل في ٧ نوفمبر ٢٠٢٦