> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# webhooks الكيانات: أحداث المستخدم والشركة

> webhooks فورية من Didit لتغييرات كيانات المستخدم والشركة: انتقالات الحالة وتحديثات الملف، مع حقول الحمولة والتوقيع وإعادة المحاولة.



موجّه webhook الخاص بالكيانات
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\````# Goal — subscribe to entity-level webhooks and apply changes to my database

Entity webhooks fire whenever a User or Business entity changes its status or its profile data. Use them to keep your local mirror of Didit entities in sync.

\## Entity-level event catalog

\| `webhook_type` | Trigger |
\|---|---|
\| `user.status.updated` | User entity status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`). Payload includes `previous_status`. |
\| `user.data.updated` | User entity profile / counters / metadata changed. Includes `changed_fields` and a `changes` map of `{previous, current}`. |
\| `business.status.updated` | Business entity status changed. Payload includes `previous_status`. |
\| `business.data.updated` | Business entity profile or aggregates changed. Includes `changed_fields` and `changes`. |

\`activity.created` is accepted in `subscribed_events` and by the Try Webhook tester, but Didit does not deliver it for live traffic. Do not build on it.

Session-level events (`status.updated`, `data.updated`) and transaction events (`transaction.created`, `transaction.status.updated`) live alongside but are separate — see /integration/webhooks for the full catalog.

\## Register a destination

\```bash
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Entity sync",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": [
  "user.status.updated",
  "user.data.updated",
  "business.status.updated",
  "business.data.updated"
]
}'
\```

Persist the returned destination `secret_shared_key` — that's the HMAC signing key.

\## Payload shape

Entity payloads are flat: there is no `data` wrapper and no `event` key. Read `webhook_type`.

\```json
\{
"event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
"webhook_type": "user.status.updated",
"timestamp": 1776333600,
"created_at": 1776333594,
"application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"environment": "live",
"vendor_user_id": "9c7d2a30-...",
"vendor_data": "user-42",
"status": "BLOCKED",
"previous_status": "ACTIVE"
}
\```

\`business.*` events use `vendor_business_id` instead of `vendor_user_id`.
\`user.data.updated` / `business.data.updated` payloads keep `status` and add `changed_fields` (array) and `changes` (`{field: {previous, current}}`). Use these to apply minimal diffs to your DB.

\## Verify the signature

Verify X-Signature-V2 (recommended): HMAC-SHA256 of the canonical JSON body with the destination `secret_shared_key`, then a constant-time compare, and reject an X-Timestamp older than 300 seconds. See /integration/webhooks for the signature headers and code samples. Respond `2xx` within **5 seconds**. On a 5xx, 404, timeout or connection failure Didit retries up to 2 times (about 1 minute, then about 4 minutes later); see /integration/webhooks#retry-policy.

\## Idempotency

Every delivery carries a unique `event_id`. De-dupe on it. Fallback compound key: `(application_id, webhook_type, vendor_data, timestamp)`.

\## Failure modes

\- Wrong `webhook_version` (e.g. v2) → singular fields and older event names; v3 is required for entity events plural-array contract.
\- Slow handler → retried; budget < 5s; do heavy work async.
\- Unknown event type → log and 200; new event types may be added.

\## Apply-decision pseudocode

\```ts
switch (event.webhook_type) {
case "user.status.updated":
await db.users.update({ vendor_data: event.vendor_data }, { status: event.status });
break;
case "user.data.updated":
for (const field of event.changed_fields) {
  await db.users.update({ vendor_data: event.vendor_data }, { [field]: event.changes[field].current });
}
break;
case "business.status.updated":
case "business.data.updated": /* same shape, businesses table, keyed by vendor_business_id */ break;
}
\```

\## Sources of truth

\- /integration/webhooks — destinations, signatures, retries, full event catalog
\- /management-api/webhook/create-destination — endpoint schema
\- /entities/users/operations — operations that emit user events
\- /entities/businesses/operations — operations that emit business events
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

الصق في

يُرسَل webhook عند كل تغيير في حالة كيان من نوع User أو Business أو في بيانات ملفه التعريفي، حتى يتمكن نظامك من الاستجابة في الوقت الفعلي.
استخدم webhooks الكيانات لمزامنة بيانات الملف التعريفي، أو لنقل حالات الحظر إلى أنظمة أخرى، أو لتشغيل مسارات الامتثال اللاحقة.## كتالوج الأحداث| الحدث | المُشغِّل |
| - | - |
| `user.status.updated` | تتغير حالة كيان User (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`) |
| `user.data.updated` | تتغير حقول الملف التعريفي لكيان User (الاسم، وتاريخ الميلاد، والصورة الشخصية، والعدادات المجمّعة، والبيانات الوصفية) |
| `business.status.updated` | تتغير حالة كيان Business |
| `business.data.updated` | تتغير حقول الملف التعريفي لكيان Business (الاسم القانوني، ورقم التسجيل، والدولة، والعدادات) |> [!NOTE]
>
> يُقبل `activity.created` في `subscribed_events` ويغطيه **Try Webhook** للاختبار، لكن Didit لا يرسله حاليًا لحركة المرور الفعلية.
> لا تبنِ عكسًا للجدول الزمني اعتمادًا عليه.ترسل Didit أيضًا أحداث الجلسات والمعاملات وجلسات الشركات التي تشير إلى حقول الكيانات. انظر:- [webhooks التحقق من الشركات (KYB)](https://docs.didit.me/ar/business-verification/webhooks.md): أحداث جلسات الشركات
- [webhooks مراقبة المعاملات](https://docs.didit.me/ar/transaction-monitoring/webhooks.md): أحداث المعاملات
- [مرجع webhooks](https://docs.didit.me/ar/integration/webhooks.md): التحقق من التوقيع، وإعادة المحاولة، والوجهات## بنية الحمولةwebhooks الكيانات مسطّحة: لا يوجد غلاف `data` ولا مفتاح `event`.
اقرأ `webhook_type` لتوجيه الحدث.```json theme={null}
{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "user.status.updated",
  "timestamp": 1776333600,
  "created_at": 1776333594,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}
```| الحقل | الوصف |
| - | - |
| `vendor_user_id` / `vendor_business_id` | معرّف Didit للكيان. تستخدم أحداث `business.*` الحقل `vendor_business_id`. |
| `vendor_data` | معرّفك للكيان. |
| `status` | `ACTIVE` أو `FLAGGED` أو `BLOCKED`. |
| `previous_status` | يظهر فقط في `*.status.updated`. |
| `changed_fields` و`changes` | يظهران فقط في `*.data.updated`. |
| `created_at` | ثوانٍ منذ حقبة Unix وقت آخر تحديث للكيان. |
| `timestamp` | ثوانٍ منذ حقبة Unix وقت إرسال Didit للـ webhook. |### `user.status.updated` / `business.status.updated`يُرسَل مع كل تغيير في الحالة.
تتضمن الحمولة `status` و`previous_status`.
لا توضح سبب تغيّر الحالة: افتح الكيان في Business Console إذا احتجت إلى معرفة السبب.### `user.data.updated` / `business.data.updated`يُرسَل عند تغيّر حقول الملف التعريفي.
يسرد `changed_fields` الحقول التي تغيّرت، ويحمل `changes` القيمتين `previous` و`current` لكل حقل.```json theme={null}
{
  "event_id": "5d1e8f9a-0c32-4b6a-a7b6-2b9d6f0a3c41",
  "webhook_type": "user.data.updated",
  "timestamp": 1776333700,
  "created_at": 1776333694,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "ACTIVE",
  "changed_fields": ["full_name", "session_count"],
  "changes": {
    "full_name": { "previous": null, "current": "John Doe" },
    "session_count": { "previous": 2, "current": 3 }
  }
}
```الحقول التي قد تظهر في `changed_fields` هي:- User: `vendor_data`، و`display_name`، و`full_name`، و`date_of_birth`، و`metadata`، و`portrait_image`، و`issuing_states`، و`approved_emails`، و`approved_phones`، و`features`، و`session_count`، و`approved_count`، و`declined_count`، و`in_review_count`، و`first_session_at`، و`last_session_at`.
- Business: `vendor_data`، و`display_name`، و`metadata`، و`legal_name`، و`registration_number`، و`country_code`، و`session_count`، و`approved_count`، و`declined_count`، و`in_review_count`، و`features`، و`first_session_at`، و`last_session_at`.استخدم `changed_fields` و`changes` لمزامنة الحقول التي تغيّرت فقط.## الإرسال وإعادة المحاولة والتوقيعتتبع جميع webhooks الكيانات عقد التسليم القياسي:- **موقَّع** بخوارزمية HMAC-SHA256 في الرأس `X-Signature-V2` (موصى به)، باستخدام `secret_shared_key` الخاص بالوجهة. كما يُرسل الرأس `X-Signature` والرأس `X-Signature-Simple` القديم أيضًا، إلى جانب `X-Timestamp`.
- **تُعاد** المحاولة حتى مرتين، بعد نحو دقيقة ونحو 4 دقائق، عندما ترد endpoint الخاص بك برمز 5xx أو 404، أو عند انتهاء مهلة الاتصال أو فشله. يتضمن [مرجع webhooks](https://docs.didit.me/ar/integration/webhooks.md#سياسة-إعادة-المحاولة) سياسة إعادة المحاولة كاملة.
- **‏idempotency**: لكل webhook `event_id` فريد في الحمولة، لذا أزل التكرار من جهتك.انظر [مرجع webhooks](https://docs.didit.me/ar/integration/webhooks.md) لإعداد الوجهة وأمثلة كود التحقق من التوقيع.## الاشتراكاشترك في أحداث الكيانات على وجهة webhook عبر Management API أو Business Console:```bash theme={null}
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Entity sync",
    "url": "https://yourapp.com/webhooks/didit",
    "subscribed_events": [
      "user.status.updated",
      "user.data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'
```## الخطوات التالية> [card] [مرجع webhooks](https://docs.didit.me/ar/integration/webhooks.md)
>
> الوجهات، والتوقيعات، وإعادة المحاولة، والتحقق.> [card] [إنشاء وجهة](https://docs.didit.me/ar/management-api/webhook/create-destination.md)
>
> سجّل endpoint جديد لـ webhook.> [card] [عمليات المستخدم](https://docs.didit.me/ar/entities/users/operations.md)
>
> التغييرات التي تشغّل webhooks المستخدم.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.