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

أحداث منح الاستحقاق عبر 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 الذي يجب على العميل زيارته لإكمال الموافقة. يحاول Dodo Payments إنشاءه عند إنشاء المنح، لذلك قد يتضمنه entitlement_grant.created؛ وإذا كان null، فستتم تعبئته عندما يبدأ العميل تدفق القبول من Customer Portal. تظل المنحة في حالة Pending حتى يمنح العميل التفويض.
التكاملات المباشرة مع المنصة (Telegram وFramer وDigital Files) تبقى في حالة Pending لفترة وجيزة فقط أثناء تنفيذ استدعاء المنصة، ثم تنتقل إلى Delivered.

entitlement_grant.delivered

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

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`). قابل للاسترداد: تؤدي إعادة المحاولة الناجحة إلى إعادة منح الصلاحية.
`subscription_paused`	تم إيقاف الاشتراك مؤقتًا (`subscription.paused`). قابل للاسترداد: تؤدي الاستئناف إلى إعادة منح الصلاحية.
`subscription_expired`	وصل الاشتراك إلى نهاية مدته (`subscription.expired`).
`plan_changed`	تم تغيير الخطة؛ وتُلغى المنح القديمة قبل إصدار المنح الجديدة (`subscription.plan_changed`).
`refund`	تمت معالجة استرداد للمبلغ المدفوع لمرة واحدة في الأصل (`refund.succeeded`).
`manual`	ألغى التاجر المنحة عبر API أو لوحة المعلومات. لا تتم إعادة منح الصلاحيات الملغاة يدويًا تلقائيًا عند تجديد الاشتراك.
`license_key_disabled`	تم تعطيل مفتاح الترخيص المرتبط بمنحة مفتاح الترخيص. تُعاد تفعيل المنحة تلقائيًا إذا أُعيد تفعيل المفتاح.
`platform_external`	خرج جانب المنصة من تكامل عن التزامن (على سبيل المثال، أُزيل دور Discord يدويًا، أو فقد GitHub App صلاحية الوصول إلى المستودع، أو اكتشفت عملية مطابقة missing target). لا تتم إعادة منح الصلاحية تلقائيًا عند تجديد الاشتراك إلى أن تُحل مشكلة المنصة الأساسية.

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

يكون الحقل 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": {
      "id": "lic_4hQ2mZ8bR",
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "status": "active",
      "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": {},
    "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": {},
    "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": {},
    "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": {},
    "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": {
      "id": "lic_4hQ2mZ8bR",
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "status": "disabled",
      "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": {},
    "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": {},
    "created_at": "2026-05-01T10:36:00Z",
    "updated_at": "2026-05-01T10:36:21Z"
  }
}

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

فعّل الميزات التابعة عندما تصل المنحة إلى Delivered. يخبرك حدث payment.succeeded بأن الأموال قد تمت تسويتها؛ لكنه لا يخبرك بأن العميل حصل بالفعل على مستودع GitHub أو دور Discord. تعامل مع entitlement_grant.delivered، وكذلك مع entitlement_grant.created باستخدام status: "Delivered"، لأن المنحة التي يتم تسليمها عند الإنشاء لا تطلق أي حدث delivered.
اربط revocation_reason بتدفقات الاحتفاظ. يعني إلغاء subscription_on_hold عادةً فشل بطاقة العميل، وستعيد عملية التجديد التالية منح الوصول. أما إلغاء manual أو subscription_cancelled فيكون مقصودًا. تعامل معها بشكل مختلف في رسائل العملاء.
اكتشف التكرارات باستخدام الترويسة webhook-id، وليس id الخاص بالمنحة. تُصدر المنحة created مرة واحدة، لكن يمكن أن يُطلق كل من delivered وrevoked أكثر من مرة، لأن المنحة الملغاة يمكن استعادتها ثم إلغاؤها مرة أخرى. ولا يكون failed نهائيًا دائمًا: إذ لا يزال من الممكن تسليم منحة OAuth الفاشلة. كما يمكن لإعادة التسليم من نظام webhook أن تكرر حدثًا ما. تخطَّ التكرارات باستخدام webhook-id، واجعل سجلات المنح الخاصة بك تعتمد على id الخاص بالمنحة.
اقرأ 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. وإذا كان null، فانتظر حدثًا لاحقًا أو وجّه العميل إلى Customer Portal. أرسل عنوان URL بالبريد الإلكتروني إلى العميل أو اعرضه في تطبيقك لإتاحة التسليم.

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,
    "id": "<string>",
    "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`)

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