> ## 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. # إنشاء وجهة Webhook عبر API > سجّل وجهة webhook جديدة في Didit مع الإصدار والأحداث المشترك فيها والسر المشترك الخاص بالوجهة. عمليات webhook برمجية بالدفع لكل استدعاء. مطالبة واجهة برمجة التطبيقات لإنشاء وجهة webhook نسخ الموجّه إلى الحافظة \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

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

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
الصق في تتيح لك وجهات webhook إرسال أحداث Didit المختلفة إلى عناوين URL مختلفة. لكل وجهة `secret_shared_key` و`webhook_version` وقائمة `subscribed_events` خاصة بها.## كيف يعمل `subscribed_events``subscribed_events` مصفوفة مطلوبة تحتوي على أسماء أحداث مطابقة تمامًا. لا يرسل Didit webhook إلى هذه الوجهة إلا عندما تطابق قيمة `webhook_type` في payload واحدة من القيم الموجودة في المصفوفة.- أضف حدثاً واحداً على الأقل. - استخدم أسماء الأحداث المدعومة الواردة أدناه فقط. - أضف كل حدث تريد تسليمه؛ لا توجد قيمة بديلة شاملة مثل `*` أو `all`. - لتوجيه مجالات المنتج المختلفة إلى أنظمة مختلفة، أنشئ وجهات متعددة بقوائم `subscribed_events` مختلفة.## كتالوج الأحداث| الحدث | اشترك عند الحاجة إلى ذلك | | - | - | | `status.updated` | تغيّر حالة جلسة التحقق من المستخدمين (KYC) أو التحقق من الشركات (KYB). تتضمن payload الخاصة بـ KYB القيمة `session_kind: "business"` و`business_session_id`. | | `data.updated` | تصحيح بيانات التحقق في الجلسة أو تحديثها بعد إنشاء الجلسة، مثل تعديلات المراجِع على بيانات KYC أو إثبات العنوان أو KYB. | | `user.status.updated` | تغيّر حالة كيان User، على سبيل المثال `ACTIVE` أو `FLAGGED` أو `BLOCKED`. | | `user.data.updated` | تغيّر ملف كيان User أو عداداته أو بياناته الوصفية أو مستنداته أو حقول التحقق المجمّعة. | | `business.status.updated` | تغيّر حالة كيان Business، على سبيل المثال بعد المراجعة اليدوية أو نتائج KYB أو إجراء على قائمة الحظر. | | `business.data.updated` | تغيّر ملف كيان Business أو عداداته أو بياناته الوصفية أو حقول التسجيل أو حقول التحقق المجمّعة. | | `activity.created` | مقبول في `subscribed_events` ومشمول في **Try Webhook**، لكن Didit لا يرسله حالياً في حركة المرور الفعلية. | | `transaction.created` | إنشاء معاملة في مراقبة المعاملات واكتمال تقييم القواعد الأولي لها. | | `transaction.status.updated` | تغيّر حالة المعاملة بعد تطبيق القواعد أو مراجعة المحلل أو المعالجة أو تحديثات المزوّد أو إجراءات API أو وحدة التحكم؛ كما يُرسل مرة واحدة عند اكتمال فحص عملات مشفرة أُعيدت محاولته في الخلفية. | | `travel_rule.status.updated` | تغيّر حالة تبادل [Travel Rule](https://docs.didit.me/ar/transaction-monitoring/travel-rule.md). | | `workflow.compliance_changed` | تغيّر حالة امتثال سير عمل منشور بعد إعادة التقييم. | | `transaction_rule_suggestions.created` | تقترح عملية تشغيل اقتراحات القواعد تغييرات جديدة على القواعد. |كما تُقبل عائلتا الأحداث `investigator.*` و`auth.*`. ترد كل الأحداث وpayload الخاصة بها في [Webhooks](https://docs.didit.me/ar/integration/webhooks.md#أنواع-الأحداث).مجموعات الاشتراك الشائعة:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```لأمثلة payload وكود التوقيع، راجع [دليل webhooks](https://docs.didit.me/ar/integration/webhooks.md). ## OpenAPI ````yaml ar/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: إنشاء وجهة webhook description: >- أنشئ وجهة webhook. تتضمن الاستجابة سر توقيع HMAC المُنشأ تلقائياً `secret_shared_key` (يمكن قراءته أيضاً لاحقاً عبر `GET /v3/webhook/destinations/{destination_uuid}/`). أرسل دائماً `subscribed_events` مع حدث واحد على الأقل (بدون أحرف بدل): يتم رفض القائمة الفارغة الصريحة برمز 400، ويؤدي حذف الحقل إلى إنشاء وجهة غير مشتركة في أي شيء، والتي لن تتلقى أي webhook أبداً. يجب أن يكون الزوج `(application, url)` فريداً بين وجهات التطبيق. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- اسم سهل القراءة يُعرض في Console ← Webhooks. يساعد في التمييز بين الوجهات عندما يكون لديك عدة وجهات (مثل "Prod"، "Staging mirror"). url: type: string format: uri description: >- رابط HTTPS الذي سيتلقى طلبات `POST`. يجب أن يكون فريداً بين وجهات التطبيق. استخدم endpoint مستقراً ومؤمّناً: تعيد Didit محاولة عمليات التسليم الفاشلة وفق جدول زمني تصاعدي. maxLength: 2000 enabled: type: boolean default: true description: >- عندما تكون القيمة `false`، يتم حفظ الوجهة ولكن Didit لن ترسل إليها أي webhooks. هذا مفيد لإعدادات بيئات الاختبار التي تريد إبقاءها معلقة مؤقتاً. webhook_version: type: string enum: - v1 - v2 - v3 description: >- إصدار مخطط payload الذي سترسله Didit. الإصدار `v3` هو التنسيق الحالي/الموصى به؛ ويتم الاحتفاظ بالإصدارات الأقدم للتوافق مع عمليات التكامل القديمة. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- الأحداث المراد تسليمها. مطلوبة عملياً: يتم رفض `[]` الصريحة بالرمز 400، ويؤدي حذف الحقل إلى إنشاء وجهة بدون أي اشتراكات ولا تتلقى أي شيء. examples: session_updates: summary: تحديثات حالة الجلسة والبيانات value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: تحديثات مراقبة المعاملات value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: تحديثات كيانات المستخدم والشركة value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- تم إنشاء الوجهة. `secret_shared_key` هو السر المشترك لتوقيع HMAC — خزّنه الآن. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- معرّف الوجهة الثابت. يُستخدم كـ `{destination_uuid}` في الاستدعاءات اللاحقة. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- سر توقيع HMAC يتم إنشاؤه تلقائياً ويكون مرتبطاً بهذه الوجهة (token آمن لعناوين URL بطول 43 حرفاً). استخدمه للتحقق من رؤوس التوقيع على webhooks الواردة. يتم إرجاعه دائماً بالكامل للمتصلين عبر مفتاح API؛ ويحتاج مستخدمو لوحة التحكم إلى إذن `read:webhooks`، وإلا فسيظهر لهم نص فارغ. secret_last4: type: string description: >- آخر أربعة أحرف من سر التوقيع الحالي للوجهة، لتتمكن من التمييز بين الأسرار. غير كافية للتحقق من التوقيع. previous_secret_expires_at: type: string format: date-time nullable: true description: >- يُعيَّن لمدة 24 ساعة بعد تدوير سر التوقيع للوجهة في Business Console. حتى هذا الوقت، يحمل كل تسليم إلى الوجهة أيضاً `X-Signature-Previous` و `X-Signature-V2-Previous` و `X-Signature-Simple-Previous`، المنشأة باستخدام السر المُستبدل (انظر [التحقق من التوقيع](/ar/integration/webhooks#التحقق-من-التوقيع)). تكون القيمة `null` في حال عدم حدوث أي تدوير خلال آخر 24 ساعة. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- البريد الإلكتروني لعضو Business Console الذي أنشأ الوجهة. يكون `null` بالنسبة للوجهة التي تم إنشاؤها باستخدام مفتاح API. created_by_name: type: string nullable: true description: >- اسم عضو Business Console الذي أنشأ الوجهة. `null` لوجهة تم إنشاؤها باستخدام مفتاح API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- حالة التشغيل للتسليم. `failing`: فشل 3 أحداث متتالية أو أكثر في أول محاولة تسليم لها منذ آخر استجابة ناجحة للوجهة (راجع `failing_streak`). `degraded`: ليست في حالة failing، ولكن فشلت محاولة تسليم خلال آخر 24 ساعة ولم تنجح أي محاولة لاحقة في تسليم ذلك الحدث؛ وستؤدي إعادة المحاولة أو إعادة الإرسال التي تنجح في تسليمه إلى محو هذه الحالة. `healthy`: ليست في أي من الحالتين السابقتين. مستقلة عن `enabled`. المحاولة الفاشلة هي المحاولة التي تمت الاستجابة لها برمز HTTP 400 أو أعلى، أو لم تتم الاستجابة لها على الإطلاق. failing_streak: type: integer description: >- عدد الأحداث المتتالية التي فشلت محاولة تسليمها الأولى منذ آخر استجابة ناجحة للوجهة، خلال آخر 30 يوماً. لا تُحتسب عمليات إعادة المحاولة، وأي محاولة ناجحة، بما في ذلك إعادة المحاولة أو إعادة الإرسال، تنهي سلسلة الفشل. تكون القيمة `0` عندما لا يفشل أي حدث منذ آخر نجاح. failing_since: type: string format: date-time nullable: true description: >- وقت إجراء أول محاولة فاشلة في `failing_streak` الحالية. تكون القيمة `null` عندما تكون `failing_streak` تساوي `0`. last_success_at: type: string format: date-time nullable: true description: >- وقت آخر استجابة من الوجهة لتسليم بحالة HTTP أقل من 400، خلال آخر 30 يوماً. وتكون القيمة `null` إذا لم تُجب خلال تلك الفترة بتسليم ذي حالة HTTP أقل من 400. environment: type: string enum: - live - sandbox description: بيئة التطبيق الذي يملك الوجهة. summary: type: object description: >- مقاييس التسليم لآخر `metrics_window_days` (30) يوماً. `last_delivery_at` هي أحدث محاولة، بغض النظر عن وقت إجرائها. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- طول النافذة الزمنية بالأيام التي تغطيها مقاييس الملخص الأخرى. القيمة دائماً `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- فشل التحقق — عادةً بسبب تكرار عنوان URL، أو عدم وجود/عدم صلاحية `subscribed_events`، أو اسم حدث غير معروف. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- مفتاح API مفقود أو غير صالح أو منتهي الصلاحية أو مخصص لتطبيق مختلف. يُرجع المفتاح المفقود رمز الحالة `403`؛ بينما يُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية رمز الحالة `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: تم تجاوز حد المعدل؛ تراجع مؤقتاً وأعد المحاولة. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- أداة تصفية الأحداث لوجهة webhook هذه. تسلّم Didit فقط إشعارات webhook التي يتطابق نوع الحدث الخاص بها تماماً مع إحدى هذه القيم — لا يوجد اشتراك باستخدام أحرف البدل. عند الإرسال، يجب أن تحتوي القائمة على حدث صالح واحد على الأقل (يتم رفض `[]` الصريحة بالرمز 400)؛ والوجهة التي تكون قائمتها فارغة (تم إغفال الحقل عند الإنشاء) لا تتلقى أي شيء. عند التحديث، يتم استبدال القائمة بالكامل ولا تُدمج أبداً. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- اسم حدث webhook المدعوم. استخدم هذه النصوص بدقة في `subscribed_events`؛ حيث يتم رفض القيم غير المدعومة. enum: - 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.