منح الاستحقاق

أحداث منح الاستحقاق عبر webhook

يتم إطلاق هذه الأحداث كلما تغيرت حالة منحة استحقاق العميل، على سبيل المثال عند إنشاء مفتاح ترخيص، أو تعيين دور Discord، أو توفير رابط تنزيل، أو سحب الوصول. اشترك في هذه الأحداث للحفاظ على توافق تطبيقك مع ما يمكن لكل عميل الوصول إليه.

الحدث	الوصف
`entitlement_grant.created`	تم إنشاء صف منح جديد. تكون الحالة `Delivered` فورًا لمفاتيح الترخيص التي يتم تنفيذها تلقائيًا، و`Pending` لمفاتيح الترخيص التي يتم تنفيذها يدويًا ولكل عمليات التكامل الأخرى.
`entitlement_grant.delivered`	ينتقل المنح إلى حالة التسليم. أصبح لدى العميل الآن وصول إلى المنصة أو الملف أو مفتاح الترخيص المستحق.
`entitlement_grant.failed`	فشل التسليم ولن تتم إعادة المحاولة. افحص `error_code` و`error_message`.
`entitlement_grant.revoked`	تم سحب الوصول. افحص `revocation_reason` لفهم السبب.

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

محفزات الأحداث

entitlement_grant.created

تم إدخال صف المنحة للتو. يكون للمنحة دائمًا id ثابت من هذه النقطة فصاعدًا، حتى لو تغيرت حالتها. استخدم هذا الحدث لتسجيل أن الإنجاز قيد التقدم. بالنسبة إلى مفاتيح الترخيص التي يتم تنفيذها تلقائيًا، يُدرج الصف مباشرةً مع تعبئة status: "Delivered" وdelivered_at، لذلك يتبع حدث created واحد فقط، من دون أي تغييرات لاحقة في الحالة، ما لم يتم إلغاء المنح لاحقًا. بالنسبة إلى مفاتيح الترخيص التي يتم تنفيذها يدويًا (الاستحقاقات التي تحتوي على fulfillment_mode: manual)، يصل الصف مع status: "Pending" ومن دون كائن license_key — إذ لا يوجد مفتاح بعد. يشير هذا الحدث إلى أن مفتاحًا بانتظار التنفيذ؛ وفّره عبر POST /grants/{grant_id}/license-key، ما يؤدي بعد ذلك إلى إطلاق entitlement_grant.delivered. راجع التنفيذ اليدوي. بالنسبة إلى كل عمليات التكامل الأخرى، يصل الصف مع status: "Pending". يتبع ذلك حدث delivered أو failed عند اكتمال التسليم:

عمليات التكامل المستندة إلى OAuth (Discord وGitHub وNotion) تتضمن oauth_url يجب على العميل زيارته لإكمال الموافقة. يظل المنح في حالة Pending حتى يمنح العميل التفويض.
عمليات التكامل المباشرة مع المنصة (Telegram وFramer وDigital Files) تبقى في حالة Pending لفترة وجيزة فقط أثناء تنفيذ استدعاء المنصة، ثم تنتقل إلى Delivered.

entitlement_grant.delivered

انتقل المنح من Pending إلى Delivered. أصبح لدى العميل الآن الوصول الموضح في الاستحقاق. استخدم هذا الحدث لفتح الميزات التابعة في أنظمتك، مثل تجهيز مساحة عمل أو إرسال رسالة ترحيب مخصصة أو وضع علامة “fulfilled”. يسجل الحقل delivered_at في الحمولة وقت اكتمال التسليم. بالنسبة إلى المنح التي وصلت بحالة Delivered عند الإنشاء، ستتلقى حدثي created وdelivered متتاليين.

entitlement_grant.failed

تمت محاولة التسليم وفشلت مع خطأ غير ممكن إعادة المحاولة. يوضح الحقل error_code وerror_message الفشل. تشمل الأسباب الشائعة إلغاء رمز OAuth، أو رفض إذن منصة، أو هدف مفقود (مثل، تم حذف خادم Discord).

اعتبر entitlement_grant.failed قابلا للتنفيذ. دفع العميل ولكن لم يحصل على الوصول. أظهر الفشل لفريق الدعم الخاص بك أو قم بإعادة المنح بمجرد حل المشكلة الأساسية.

entitlement_grant.revoked

تم سحب الوصول على مستوى المنصة: تم إزالة دور Discord، تم إزالة المتعاون في GitHub، تم تعطيل مفتاح الترخيص، لم يعد يتم إصدار روابط تحميل الملفات. يسجل حقل revocation_reason المُحرك.

`revocation_reason`	المُشغِّل
`subscription_cancelled`	تم إلغاء اشتراك العميل (حدث `subscription.cancelled`).
`subscription_on_hold`	الاشتراك معلّق بسبب فشل التجديد (`subscription.on_hold`). قابل للاسترداد: تؤدي إعادة المحاولة الناجحة إلى إعادة منح الصلاحية.
`SubscriptionPaused`	تم إيقاف الاشتراك مؤقتًا (`subscription.paused`). قابل للاسترداد: تؤدي استئناف الاشتراك إلى إعادة منح الصلاحية.
`subscription_expired`	وصل الاشتراك إلى نهاية مدته (`subscription.expired`).
`plan_changed`	تغيّرت الخطة؛ يتم إبطال المنح القديمة قبل إصدار المنح الجديدة (`subscription.plan_changed`).
`refund`	تمت معالجة استرداد للمبلغ الأصلي المدفوع لمرة واحدة (`refund.succeeded`).
`manual`	ألغى التاجر المنحة عبر API أو لوحة المعلومات. لا تتم إعادة منح الصلاحيات المُلغاة يدويًا تلقائيًا عند تجديد الاشتراك.
`license_key_disabled`	تم تعطيل مفتاح الترخيص المرتبط بمنحة مفتاح الترخيص. تتم إعادة تفعيل المنحة تلقائيًا إذا أُعيد تمكين المفتاح.
`platform_external`	أصبح جانب المنصة من أحد التكاملات غير متزامن (على سبيل المثال، أُزيل دور Discord يدويًا، أو فقد GitHub App صلاحية الوصول إلى المستودع، أو اكتشفت عملية مطابقة عدم وجود الهدف). لا تتم إعادة منح الصلاحية تلقائيًا عند تجديد الاشتراك إلى أن تُحل مشكلة المنصة الأساسية.

أنواع الحمولة

يكون الحقل data دائمًا كائنًا من نوع EntitlementGrantResponse. تحمل الحمولة حقل integration_type (مثل license_key وdigital_files وdiscord) حتى تتمكن من التعرّف مباشرةً على نوع المنح. كما تُرفق ثلاثة أنواع من عمليات التكامل كائنات متداخلة إضافية:

يُضمَّن license_key عندما يكون integration_type هو license_key ويكون قد تم إصدار مفتاح. ويحتوي على المفتاح المُنشأ وتاريخ الانتهاء واستخدام التفعيل. وبالنسبة إلى منح يتم تنفيذها يدويًا ولا تزال في حالة Pending، يكون هذا الكائن null إلى أن تنفذ المنح.
يُضمَّن digital_product_delivery عندما يكون integration_type هو digital_files. ويحتوي على عناوين URL لتنزيلات موقعة مسبقًا، وinstructions الاختياري، وexternal_url الاختياري.
يُضمَّن feature عندما يكون integration_type هو feature_flag. ويحتوي على feature_type وfeature_id للقدرة التي يمنحها المنح.

بالنسبة إلى جميع أنواع عمليات التكامل الأخرى (Discord وGitHub وTelegram وFigma وFramer وNotion)، تكون هذه الحقول المتداخلة null؛ إذ يتم تسجيل الإعدادات ذات الصلة في الاستحقاق نفسه، وليس في المنح.

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

مفتاح الترخيص المسُلم (`entitlement_grant.delivered`)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:25:33.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Delivered",
    "integration_type": "license_key",
    "license_key": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "expires_at": "2027-05-01T00:00:00Z",
      "activations_used": 0,
      "activations_limit": 5
    },
    "digital_product_delivery": null,
    "delivered_at": "2026-05-01T10:25:33Z",
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-05-01T10:25:33Z"
  }
}

مفتاح الترخيص قيد التفعيل اليدوي (`entitlement_grant.created`)

يتم إطلاقه عندما يشتري العميل منتجًا يستخدم استحقاق مفتاح الترخيص الخاص به fulfillment_mode: manual. يكون المنح في حالة Pending ومن دون كائن license_key بعد — يجب على التاجر توفير المفتاح.

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.created",
  "timestamp": "2026-05-01T10:24:00.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Pending",
    "integration_type": "license_key",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:24:00Z",
    "updated_at": "2026-05-01T10:24:00Z"
  }
}

الملفات الرقمية المسلمة (`entitlement_grant.delivered`)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:30:12.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_2P9rQwYvMxTnKoCb4",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_files_J3kLmN4oP5",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Delivered",
    "integration_type": "digital_files",
    "license_key": null,
    "digital_product_delivery": {
      "files": [
        {
          "file_id": "df_a4f6c1de",
          "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
          "filename": "pro-bundle.zip",
          "content_type": "application/zip",
          "file_size": 18742390,
          "expires_in": 900
        }
      ],
      "instructions": "Unzip and run setup.sh from the project root.",
      "external_url": null
    },
    "delivered_at": "2026-05-01T10:30:12Z",
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:30:12Z",
    "updated_at": "2026-05-01T10:30:12Z"
  }
}

تم إنشاء دور Discord وعالق (`entitlement_grant.created`)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.created",
  "timestamp": "2026-05-01T10:31:00.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_DiscordPending5L",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_discord_patrons",
    "customer_id": "cus_abc123",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "Pending",
    "integration_type": "discord",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": "https://discord.com/oauth2/authorize?...",
    "oauth_expires_at": "2026-05-08T10:31:00Z",
    "metadata": null,
    "created_at": "2026-05-01T10:31:00Z",
    "updated_at": "2026-05-01T10:31:00Z"
  }
}

منح مُلغى بسبب إلغاء اشتراك (`entitlement_grant.revoked`)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.revoked",
  "timestamp": "2026-06-15T08:12:44.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "Revoked",
    "integration_type": "license_key",
    "revocation_reason": "subscription_cancelled",
    "license_key": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "expires_at": null,
      "activations_used": 1,
      "activations_limit": 5
    },
    "digital_product_delivery": null,
    "delivered_at": "2026-05-01T10:25:33Z",
    "revoked_at": "2026-06-15T08:12:44Z",
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-06-15T08:12:44Z"
  }
}

فشلت عملية التسليم (`entitlement_grant.failed`)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.failed",
  "timestamp": "2026-05-01T10:36:21.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_GhFailed7Z",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_github_repo",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Failed",
    "integration_type": "github",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": "github_permission_denied",
    "error_message": "Repository access could not be granted: the GitHub App installation no longer has permission on this repository.",
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:36:00Z",
    "updated_at": "2026-05-01T10:36:21Z"
  }
}

نصائح للتكامل

انتظر entitlement_grant.delivered قبل فتح الميزات التابعة. يخبرك حدث payment.succeeded بأن الدفعة قد تمت تسويتها؛ لكنه لا يخبرك بأن العميل لديه مستودع GitHub أو دور Discord بعد. يُعد حدث delivered مصدر الحقيقة بالنسبة إلى التنفيذ.
اربط revocation_reason بتدفقات الاحتفاظ. يعني إلغاء subscription_on_hold عادةً أن بطاقة العميل فشلت، وأن التجديد التالي سيمنح الوصول من جديد. أما إلغاء manual أو subscription_cancelled فيكون مقصودًا. تعامل معها بشكل مختلف في رسائل العملاء.
استخدم id الخاص بالمنح كمفتاح idempotency. يطلق المنح الواحد حدث created واحدًا كحد أقصى، وحدثًا نهائيًا واحدًا كحد أقصى (delivered أو failed)، وحدث revoked واحدًا كحد أقصى. يمكن أن تؤدي عمليات إعادة التسليم من نظام webhook إلى تكرار الأحداث؛ أزل التكرار باستخدام id الخاص بالمنح بالإضافة إلى type.
اقرأ integration_type للتعرّف على نوع المنح. تحمل الحمولة integration_type مباشرةً (مثل license_key وdigital_files وdiscord). تتم تعبئة الكائنين المتداخلين license_key وdigital_product_delivery بعد تسليم المنح الخاص بهما؛ بينما يظل منح مفتاح الترخيص الذي يتم تنفيذه يدويًا في حالة Pending مع integration_type: "license_key" وnull license_key إلى أن تنفذه.
بالنسبة إلى المنح المستندة إلى OAuth، اعرض oauth_url للعميل. يتضمن حدث entitlement_grant.created لتدفقات المشتركين في Discord أو GitHub أو Notion كلاً من oauth_url وoauth_expires_at. أرسله إلى العميل عبر البريد الإلكتروني أو اعرضه في تطبيقك لتمكين التسليم.

Detailed view of a single entitlement grant: who it's for, its lifecycle state, and any integration-specific delivery payload.

brand_id

string

مطلوب

Brand id this grant belongs to.

business_id

string

مطلوب

Identifier of the business that owns the grant.

created_at

string<date-time>

مطلوب

Timestamp when the grant was created.

customer_id

string

مطلوب

Identifier of the customer the grant was issued to.

entitlement_id

string

مطلوب

Identifier of the entitlement this grant was issued from.

string

مطلوب

Unique identifier of the grant.

integration_type

enum<string>

مطلوب

The integration type of the grant's entitlement (e.g. license_key).

الخيارات المتاحة:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

مطلوب

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

مطلوب

Lifecycle status of the grant.

الخيارات المتاحة:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

مطلوب

Timestamp when the grant was last modified.

delivered_at

string<date-time> | null

Timestamp when the grant transitioned to delivered, when applicable.

digital_product_delivery

null | Digital Product Delivery · object

Digital-product-delivery payload, present when the entitlement integration is digital_files.

Show child attributes

error_code

string | null

Machine-readable code reported when delivery failed, when applicable.

error_message

string | null

Human-readable message reported when delivery failed, when applicable.

feature

null | object

Typed feature payload, present only when the entitlement integration is feature_flag; null for every other integration type.

Show child attributes

license_key

null | object

License-key delivery payload, present when the entitlement integration is license_key.

Show child attributes

oauth_expires_at

string<date-time> | null

Timestamp when oauth_url stops being valid, when applicable.

oauth_url

string | null

Customer-facing OAuth URL for OAuth-style integrations. Populated during the customer-portal accept flow; null until the customer completes that step, and on grants for non-OAuth integrations.

payment_id

string | null

Identifier of the payment that triggered this grant, when applicable.

revocation_reason

string | null

Reason recorded when the grant was revoked, when applicable.

revoked_at

string<date-time> | null

Timestamp when the grant transitioned to revoked, when applicable.

subscription_id

string | null

Identifier of the subscription that triggered this grant, when applicable.

آخر تعديل في ٢١ أغسطس ٢٠٢٦

{
  "brand_id": "<string>",
  "business_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "entitlement_id": "<string>",
  "id": "<string>",
  "metadata": {},
  "updated_at": "2023-11-07T05:31:56Z",
  "delivered_at": "2023-11-07T05:31:56Z",
  "digital_product_delivery": {
    "files": [
      {
        "download_url": "<string>",
        "expires_in": 123,
        "file_id": "<string>",
        "filename": "<string>",
        "content_type": "<string>",
        "file_size": 123
      }
    ],
    "external_url": "<string>",
    "instructions": "<string>"
  },
  "error_code": "<string>",
  "error_message": "<string>",
  "feature": {
    "feature_id": "<string>",
    "feature_type": "boolean"
  },
  "license_key": {
    "activations_used": 123,
    "key": "<string>",
    "activations_limit": 123,
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "oauth_expires_at": "2023-11-07T05:31:56Z",
  "oauth_url": "<string>",
  "payment_id": "<string>",
  "revocation_reason": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "subscription_id": "<string>"
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

أحداث منح الاستحقاق عبر webhook

محفزات الأحداث

entitlement_grant.created

entitlement_grant.delivered

entitlement_grant.failed

entitlement_grant.revoked

أنواع الحمولة

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

مفتاح الترخيص المسُلم (`entitlement_grant.delivered`)

مفتاح الترخيص قيد التفعيل اليدوي (`entitlement_grant.created`)

الملفات الرقمية المسلمة (`entitlement_grant.delivered`)

تم إنشاء دور Discord وعالق (`entitlement_grant.created`)

منح مُلغى بسبب إلغاء اشتراك (`entitlement_grant.revoked`)

فشلت عملية التسليم (`entitlement_grant.failed`)

نصائح للتكامل

​أحداث منح الاستحقاق عبر webhook

​محفزات الأحداث

​entitlement_grant.created

​entitlement_grant.delivered

​entitlement_grant.failed

​entitlement_grant.revoked

​أنواع الحمولة

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

​مفتاح الترخيص المسُلم (entitlement_grant.delivered)

​مفتاح الترخيص قيد التفعيل اليدوي (entitlement_grant.created)

​الملفات الرقمية المسلمة (entitlement_grant.delivered)

​تم إنشاء دور Discord وعالق (entitlement_grant.created)

​منح مُلغى بسبب إلغاء اشتراك (entitlement_grant.revoked)

​فشلت عملية التسليم (entitlement_grant.failed)

​نصائح للتكامل

أحداث منح الاستحقاق عبر webhook

محفزات الأحداث

entitlement_grant.created

entitlement_grant.delivered

entitlement_grant.failed

entitlement_grant.revoked

أنواع الحمولة

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

مفتاح الترخيص المسُلم (`entitlement_grant.delivered`)

مفتاح الترخيص قيد التفعيل اليدوي (`entitlement_grant.created`)

الملفات الرقمية المسلمة (`entitlement_grant.delivered`)

تم إنشاء دور Discord وعالق (`entitlement_grant.created`)

منح مُلغى بسبب إلغاء اشتراك (`entitlement_grant.revoked`)

فشلت عملية التسليم (`entitlement_grant.failed`)

نصائح للتكامل