ويب هوك التحقق من الشركات: الأحداث والحمولات والتوقيع

تُخبر webhooks الخاصة بـ KYB في Didit خادمك الخلفي متى تتغير حالة جلسة التحقق من الشركات، أو متى يغيّر المراجِع أو السجل بياناته. لكيانات الشركات أحداثها الخاصة. اشترك في الأحداث التي تهمك عبر واجهة برمجة تطبيقات وجهات webhook أو عبر Business Console.

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

أحداث الجلسات مشتركة بين جلسات المستخدمين وجلسات الشركات. يشير الحقل session_kind في payload إلى نوع الجلسة التي يتعلق بها الحدث. أحداث كيانات الشركات منفصلة عن أحداث الجلسات.

أحداث على مستوى الجلسة

الحدث	متى يُرسَل
`status.updated`	تغيّرت حالة الجلسة. بالنسبة لجلسات التحقق من الشركات (KYB)، يحمل payload القيمة `session_kind: "business"`. هذا هو الحدث الذي تتابعه لمعرفة التقدم.
`data.updated`	قام مراجِع بتعديل بيانات السجل، أو تخطّى الأشخاص الرئيسيين (Key People) أو أعاد إنشاءهم في Business Console، أو أبلغ السجل عن تغيير (عند توفر مراقبة السجل). يحدد الحقل `trigger` السبب.

لا يُرسَل data.updated عندما يرفع مقدم الطلب مستنداً أو يرسل الأشخاص الرئيسيين، أو عند انتهاء إعادة فحص AML. استخدم status.updated أو استرجع قرار الجلسة لمتابعة هذا التقدم.

أحداث كيان الشركة

الحدث	متى يُرسَل
`business.status.updated`	تغيّرت حالة كيان الشركة المرتبط (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	تغيّرت حقول ملف تعريف كيان الشركة أو عداداته المجمّعة.

اشترك في أي مجموعة من هذه الأحداث في وجهة webhook الخاصة بك. راجع webhook الكيانات للاطلاع على المرجع الكامل لأحداث كيانات الشركات والمستخدمين.

بنية payload

تستخدم webhooks الجلسات payload مسطّحاً بلا غلاف data. يُوثَّق الغلاف ورؤوس التوقيع وكل حقل مشترك في مرجع webhook. تضيف جلسة KYB الحقول التالية:

الحقل	النوع	الوصف
`session_kind`	`"business"`	تتيح لمعالج عام التفريق بين KYC وKYB.
`business_session_id`	`uuid`	مطابق لـ `session_id`.
`vendor_business_id`	string	معرّفك لكيان الشركة، إذا تم تمريره عند إنشاء الجلسة.
`status`	string	التسمية الدقيقة، مثل `"In Progress"` أو `"Approved"` أو `"Awaiting User"`. راجع الحالات.
`trigger`	string	اختياري. سبب إرسال الـ webhook. في `data.updated` الخاص بـ KYB: `"console_registry_edit"` أو `"console_key_people_skip"` أو `"console_key_people_regenerate"` أو `"kyb_registry_change"`.
`decision`	object	موجود عندما تكون `status` هي `Approved` أو `Declined` أو `In Review` أو `Abandoned`. بالشكل نفسه الوارد في `GET /v3/session/{id}/decision/`، راجع مخطط الاستجابة.
`resubmit_info`	object	موجود عندما تكون `status` هي `Resubmitted`.

`status.updated` لجلسة KYB

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

تحمل كتلة decision المصفوفات registry_checks[] وkey_people_checks[] وdocument_verifications[] وaml_screenings[] وبقية مصفوفات KYB.

`data.updated` لجلسة KYB

يحمل data.updated الغلاف المسطّح نفسه الذي يحمله status.updated، إضافة إلى trigger يوضح سبب الإرسال. عندما تكون حالة الجلسة Approved أو Declined أو In Review أو Abandoned، يحمل أيضاً decision الحالي. أعد جلب القرار لمعرفة ما تغيّر. لا يحتوي payload على قائمة changed_fields.

`business.status.updated` و`business.data.updated`

أحداث الكيانات مسطّحة أيضاً. تحمل vendor_business_id وvendor_data وstatus (ACTIVE أو FLAGGED أو BLOCKED) وcreated_at. يضيف business.status.updated الحقل previous_status. ويضيف business.data.updated الحقل changed_fields وخريطة changes بالصيغة { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

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

يُوقَّع كل webhook بخوارزمية HMAC-SHA256 باستخدام السر المشترك لوجهتك. تحقّق من نص الطلب الخام باستخدام الرأس X-Signature-V2 (موصى به)، وارفض عمليات التسليم التي يتجاوز عمر X-Timestamp فيها 300 ثانية. يسرد مرجع webhook جميع رؤوس التوقيع، وفترة التداخل عند تدوير سر التوقيع، وأمثلة الكود.

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

تؤدي استجابة 5xx أو 404، أو انتهاء المهلة، أو فشل الاتصال، إلى محاولتين لإعادة المحاولة على الأكثر، بعد نحو دقيقة ونحو 4 دقائق، ثم يُسقَط التسليم.
لا تُعاد المحاولة للاستجابات الأخرى من فئة 4xx و3xx.
تحتفظ كل إعادة محاولة بالقيمة event_id نفسها، لذا استخدمها لإزالة التكرار.
يمكنك إعادة إرسال تسليم من سجل التسليم في الوجهة. يتضمن مرجع webhook السياسة الكاملة.

الاشتراك

اشترك في الأحداث التي تهمك في وجهة webhook:

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

صفِّ جلسات الشركات من جهتك بالتحقق من session_kind === "business" داخل أحداث status.updated وdata.updated.

الخطوات التالية

مرجع webhook

الوجهات والتوقيع وإعادة المحاولات وأنماط شائعة.

الحالات

مرجع حالات الجلسة والميزات.

مخطط الاستجابة

فك ترميز payload قرار KYB.

البدء

الميزات

ملفات الشركات

المرجع

Console

ويب هوك التحقق من الشركات: الأحداث والحمولات والتوقيع

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

أحداث على مستوى الجلسة

أحداث كيان الشركة

بنية payload

`status.updated` لجلسة KYB

`data.updated` لجلسة KYB

`business.status.updated` و`business.data.updated`

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

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

الاشتراك

الخطوات التالية

مرجع webhook

الحالات

مخطط الاستجابة

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

​أحداث على مستوى الجلسة

​أحداث كيان الشركة

​بنية payload

​status.updated لجلسة KYB

​data.updated لجلسة KYB

​business.status.updated وbusiness.data.updated

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

​سياسة إعادة المحاولة

​الاشتراك

​الخطوات التالية

مرجع webhook

الحالات

مخطط الاستجابة

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

أحداث على مستوى الجلسة

أحداث كيان الشركة

بنية payload

`status.updated` لجلسة KYB

`data.updated` لجلسة KYB

`business.status.updated` و`business.data.updated`

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

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

الاشتراك

الخطوات التالية