الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​
أحداث منح الاستحقاق عبر 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 واحد دون تغييرات حالة إضافية إلا إذا تم إلغاء المنحة لاحقًا. بالنسبة إلى كل تكامل آخر يصل الصف مع status: "pending". يتبع حدث delivered أو failed بمجرد اكتمال التسليم:
  • التكاملات المستندة إلى OAuth (Discord، GitHub، Notion) تتضمن oauth_url يجب على العميل زيارته لإكمال الموافقة. تبقى المنحة pending حتى يسمح العميل بذلك.
  • التكاملات المباشرة للمنصة (Telegram، Framer، ملفات رقمية) تبقى في pending لفترة وجيزة فقط أثناء تنفيذ اتصال المنصة، ثم تنتقل إلى delivered.

​
entitlement_grant.delivered

انتقلت المنحة من pending إلى delivered. لدى العميل الآن الوصول الموصوف بواسطة الاستحقاق. استخدم هذا الحدث لفتح الميزات التابعة في أنظمتك الخاصة، على سبيل المثال لتوفير مساحة عمل، إرسال بريد ترحيبي مخصص، أو وضع علامة “منجز”. تلتقط حقل الحمولة 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). قابل للاسترداد: تولد المحاولة الناجحة إعادة منح.
subscription_expiredوصل الاشتراك إلى نهاية مدته (subscription.expired).
plan_changedتم تغيير الخطة؛ يتم إلغاء المنح القديمة قبل إصدار الجديدة (subscription.plan_changed).
refundتم معالجة استرداد للدفعة الأصلية لمرة واحدة (refund.succeeded).
manualألغى التاجر المنحة عبر API أو اللوحة. عمليات الإلغاء اليدوية لا تُمنح تلقائيًا عند تجديد الاشتراك.
license_key_disabledتم تعطيل مفتاح الترخيص خلف منحته. يتم إعادة تنشيط المنحة تلقائيًا إذا أُعيد تمكين المفتاح.
platform_externalخرج الجانب المتكامل من النظام من التزامن (على سبيل المثال، تمت إزالة دور Discord يدويًا، فقد تطبيق GitHub وصولاً للمستودع، أو تم اكتشاف عدم وجود هدف في عملية التسوية). لا يُعاد منحها تلقائيًا عند تجديد الاشتراك حتى يتم حل مشكلة النظام الأساسية.

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

حقل data دائمًا عبارة عن كائن EntitlementGrantResponse. نوعين من التكامل يرفقان كائنات متداخلة إضافية:
  • license_key يتم تضمينه عند نوع تكامل الاستحقاق هو license_key. يحتوي على المفتاح المُولد، فترة الانتهاء، واستخدام التفعيل.
  • digital_product_delivery يتم تضمينه عندما يكون نوع التكامل digital_files. يحتوي على روابط تنزيل موقعة مسبقًا، instructions اختياريًا، وexternal_url اختياريًا.
بالنسبة لجميع أنواع التكامل الأخرى (Discord، GitHub، Telegram، Framer، Notion) كلا الحقلين null؛ يتم التقاط التكوين ذي الصلة في الاستحقاق نفسه، وليس في المنحة.

​
نماذج حمولة

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

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:25:33.000000Z",
  "data": {
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "external_id": "lk_AAA111BBB222",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "delivered",
    "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.delivered)

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:30:12.000000Z",
  "data": {
    "id": "grant_2P9rQwYvMxTnKoCb4",
    "business_id": "bus_H4ekzPSlcg",
    "entitlement_id": "ent_files_J3kLmN4oP5",
    "customer_id": "cus_abc123",
    "external_id": "pay_a1b2c3d4",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "delivered",
    "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": {
    "id": "grant_DiscordPending5L",
    "business_id": "bus_H4ekzPSlcg",
    "entitlement_id": "ent_discord_patrons",
    "customer_id": "cus_abc123",
    "external_id": "sub_pro_monthly_001",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "pending",
    "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": {
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "external_id": "sub_pro_monthly_001",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "revoked",
    "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": {
    "id": "grant_GhFailed7Z",
    "business_id": "bus_H4ekzPSlcg",
    "entitlement_id": "ent_github_repo",
    "customer_id": "cus_abc123",
    "external_id": "pay_a1b2c3d4",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "failed",
    "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 كمفتاح لعدم التكرار. تصدر منحة واحدة على الأكثر حدث created واحد وعلى الأكثر حدث واحد نهائي (delivered أو failed)، وعلى الأكثر حدث revoked واحد. يمكن أن تتكرر إعادة التوجيهات من نظام webhook؛ قم بإزالة الازدواجية على id بالإضافة إلى type.
  • افحص license_key وdigital_product_delivery للتعرف على نوع التكامل. لا يحمل حمولة المنحة نوع التكامل، ولكن واحدة من هذه الكائنات المتداخلة بالضبط مليئة بالاستحقاقات ذات المفاتيح الرقمية والملفات الرقمية.
  • بالنسبة إلى المنح المستندة إلى 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.

​
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.

​
id
string
مطلوب

Unique identifier of the grant.

​
metadata
object
مطلوب

Arbitrary key-value metadata recorded on the grant.

​
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
Digital Product Delivery · object

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

​
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.

​
license_key
object

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

​
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.

Last modified on May 14, 2026