---
title: الإعداد
description: دليل خطوة بخطوة لتهيئة Webhooks في IDCloud — الخدمة الذاتية عبر البوابة الإلكترونية للويب وSDK، والتهيئة حسب العميل لتكاملات API باستخدام تنسيق Check (البرازيل فقط).
canonical: https://developer.unico.io/ar/dual-api/developers/webhooks-and-events/setup
locale: ar
generated_by: markdown-export
---

يدعم IDCloud نمطين للـ webhook، يعتمدان على طريقة تكاملك:

- **عبر البوابة الإلكترونية** — لتكاملات الويب وSDK. تهيئة ذاتية مباشرة في بوابة IDCloud.
- **حسب العميل** — لتكاملات API التي تستخدم إمكانية **تنسيق Check** (تدفق غير متزامن). يتم تهيئتها بواسطة فريق Unico. متاح في **البرازيل فقط**.

### عبر البوابة الإلكترونية (الويب وSDK)

لتسجيل نقطة نهاية الـ webhook الخاصة بك أو تحديثها، ادخل إلى بوابة IDCloud وانتقل إلى **الإعدادات > Webhook**.

#### المعلومات المطلوبة

| الحقل | الوصف |
|---|---|
| **رابط الإشعار** | نقطة النهاية التي ستتصل بها Unico لإرسال إشعارات الأحداث. يجب أن تكون قابلة للوصول عبر HTTPS. |
| **نوع المصادقة** | كيف تصادق Unico على نقطة النهاية الخاصة بك. انظر الخيارات أدناه. |
| **إعدادات إعادة المحاولة** | الحد الأقصى لعدد المحاولات والفترة الفاصلة بينها (يتم تطبيق التراجع الأسي). |
| **حد التزامن** | الحد الأقصى لعدد عمليات التسليم المتزامنة قيد التنفيذ (الحد الأقصى: **500**). |
| **المهلة الزمنية** | الحد الأقصى لوقت الانتظار لرد نقطة النهاية، بالثواني. |
| **الحالات المراد إشعارها** | مجموعة حالات العملية التي تُطلق إشعاراً. مثبّتة حالياً على `PROCESS_STATE_FINISHED`؛ غير قابلة للتهيئة في الوقت الحالي. |

#### طرق المصادقة

****OAuth2****

قدّم:

  - `endpoint` الـ Webhook
  - `URL` مزود OAuth2
  - `ClientId` مزود OAuth2
  - `Secret` مزود OAuth2

  ستطلب Unico رمز وصول من URL المزود باستخدام بيانات اعتماد العميل وستمرره إلى نقطة النهاية الخاصة بك كرمز Bearer.

****Basic Authorization****

قدّم بيانات الاعتماد بتنسيق `user:pass`. تقوم Unico بترميزها بـ Base64 وإرسالها في رأس الطلب `Authorization: Basic <encoded>` في كل استدعاء للـ webhook.

****API Key****

يُدعم تنسيقان. يتم تقسيم السلسلة عند **أول** نقطتين:

  - `header:value` — يُحدد اسم رأس طلب مخصصاً. أمثلة:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` فقط (بدون نقطتين) — تُرسل القيمة في رأس الطلب `Authorization` بدون بادئة نظام مصادقة. مثال: `abc123` → `Authorization: abc123`.

  استخدم تنسيق `header:value` عند الحاجة إلى نظام Bearer (مثل: `Authorization:Bearer <token>`)؛ أما تنسيق القيمة فقط فيُرسل القيمة الخام بدون بادئة.

****بدون مصادقة****

لا يتم إرسال بيانات اعتماد. يُوصى بهذا فقط لبيئات التطوير — يجب أن تتطلب نقاط النهاية في الإنتاج دائماً مصادقة.

#### حالات العملية التي تُطلق الإشعارات

حالياً، ترسل Unico إشعاراً في كل مرة تنتقل فيها عملية إلى:

| الحالة | الوصف |
|---|---|
| `PROCESS_STATE_FINISHED` | انتهت العملية — حالة نهائية، بغض النظر عن النتيجة. |

:::warning[قد تتطور الحالات]
قد تتغير مجموعة الحالات التي تُرسل إشعاراً بها المنصة في المستقبل. اجعل الحالات التي تستجيب لها نقطة النهاية **قابلة للتهيئة**، بحيث لا يتطلب إضافة حالة جديدة إعادة نشر خدمتك.
:::

#### تنسيق الطلب

عمليات تسليم الـ webhook هي طلبات **POST** إلى نقطة النهاية الخاصة بك. يحتوي الجسم على معرّف العملية والحالة الحالية.

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`lastEvent` و`lastEventDescription`]
يظهر هذان الحقلان في الحمولة **فقط عندما تنتهي صلاحية العملية** قبل إكمال المستخدم للرحلة. ولا يوجدان في حمولات الإتمام الطبيعية. راجع [أنواع الأحداث](/developers/webhooks-and-events/event-types) للاطلاع على المخطط الكامل وقائمة قيم `lastEvent` المحتملة.
:::

#### الرد المتوقع

يجب أن تستجيب نقطة النهاية **بشكل متزامن**:

- **نجاح**: أي حالة HTTP في نطاق `200`–`299`.
- **فشل**: أي حالة أخرى. ستعيد Unico المحاولة بتراجع أسي حتى الحد الأقصى المهيّأ لعدد المحاولات، أو حتى استلام `2xx`.

:::tip[استجب بسرعة]
اعترف بالـ webhook بسرعة (قبل انتهاء المهلة المهيّأة) وعالج الحمولة بشكل غير متزامن من طرفك. المعالجة الطويلة داخل معالج الـ webhook تزيد من احتمال انتهاء المهلة وإعادة المحاولات غير الضرورية.
:::

للاطلاع على إرشادات الأمانة (Idempotency) ومعالجة إعادة المحاولة، راجع [الأمان](/developers/webhooks-and-events/security).

### حسب العميل (API — البرازيل فقط)

:::info[البرازيل فقط]
يتوفر webhook بنمط "حسب العميل" حصرياً لتكاملات API في البرازيل التي تستخدم إمكانية **تنسيق Check** — وهو تدفق غير متزامن يتم فيه تسليم نتيجة العملية عبر webhook بدلاً من استجابة API متزامنة.
:::

لتسجيل نقطة النهاية الخاصة بك أو تحديثها، تواصل مع فريق **CS / Onboarding** الخاص بك.

#### المعلومات المطلوبة

| الحقل | الوصف |
|---|---|
| **رابط الإشعار** | نقطة النهاية التي تعرضها منظومتك لاستقبال تحديثات الحالة. يجب أن تكون قابلة للوصول عبر HTTPS. |
| **نوع المصادقة** | كيف تصادق Unico على نقطة النهاية الخاصة بك. انظر الخيارات أدناه. |
| **إعدادات إعادة المحاولة** | الحد الأقصى لعدد المحاولات والفترة الفاصلة بينها (يتم تطبيق التراجع الأسي). |
| **حد التزامن** | الحد الأقصى لعدد عمليات التسليم المتزامنة قيد التنفيذ (الحد الأقصى: **500**). |
| **المهلة الزمنية** | الحد الأقصى لوقت الانتظار لرد نقطة النهاية، بالثواني. |

#### طرق المصادقة

****OAuth2****

قدّم:

  - `endpoint` الـ Webhook
  - `URL` مزود OAuth2
  - `ClientId` مزود OAuth2
  - `Secret` مزود OAuth2

  ستطلب Unico رمز وصول من URL المزود باستخدام بيانات اعتماد العميل وستمرره إلى نقطة النهاية الخاصة بك كرمز Bearer.

****Basic Authorization****

قدّم بيانات الاعتماد بتنسيق `user:pass`. تقوم Unico بترميزها بـ Base64 وإرسالها في رأس الطلب `Authorization: Basic <encoded>` في كل استدعاء للـ webhook.

****API Key****

يُدعم تنسيقان. يتم تقسيم السلسلة عند **أول** نقطتين:

  - `header:value` — يُحدد اسم رأس طلب مخصصاً. أمثلة:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` فقط (بدون نقطتين) — تُرسل القيمة في رأس الطلب `Authorization` بدون بادئة نظام مصادقة. مثال: `abc123` → `Authorization: abc123`.

  استخدم تنسيق `header:value` عند الحاجة إلى نظام Bearer (مثل: `Authorization:Bearer <token>`)؛ أما تنسيق القيمة فقط فيُرسل القيمة الخام بدون بادئة.

****بدون مصادقة****

لا يتم إرسال بيانات اعتماد. يُوصى بهذا فقط لبيئات التطوير — يجب أن تتطلب نقاط النهاية في الإنتاج دائماً مصادقة.

#### رموز الحالة

يستخدم webhook بنمط "حسب العميل" **رموز حالة رقمية**:

| الرمز | الوصف |
|---|---|
| `2` | تباين — اكتملت العملية مع وجود تباين في التحقق من الهوية. |
| `3` | مكتملة — اكتملت العملية بنجاح. |
| `5` | خطأ — انتهت العملية بسبب خطأ. |

#### تنسيق الطلب

عمليات تسليم الـ webhook هي طلبات **POST** إلى نقطة النهاية الخاصة بك. يحتوي الجسم على معرّف المعاملة ورمز الحالة الرقمي.

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### الرد المتوقع

يجب أن تستجيب نقطة النهاية **بشكل متزامن**:

- **نجاح**: أي حالة HTTP في نطاق `200`–`299`.
- **فشل**: أي حالة أخرى. ستعيد Unico المحاولة بتراجع أسي حتى الحد الأقصى المهيّأ لعدد المحاولات، أو حتى استلام `2xx`.

:::tip[استجب بسرعة]
اعترف بالـ webhook بسرعة (قبل انتهاء المهلة المهيّأة) وعالج الحمولة بشكل غير متزامن من طرفك. المعالجة الطويلة داخل معالج الـ webhook تزيد من احتمال انتهاء المهلة وإعادة المحاولات غير الضرورية.
:::

:::warning[ضمان التسليم مرة واحدة على الأقل]
تضمن المنصة التسليم مرة واحدة على الأقل — قد يصل نفس الإشعار أكثر من مرة. طبّق الأمانة (Idempotency) من طرفك باستخدام حقل `id` للتعامل مع التكرارات بأمان.

للاطلاع على إرشادات الأمانة (Idempotency) ومعالجة إعادة المحاولة، راجع [الأمان](/developers/webhooks-and-events/security).
:::