跳转到主要内容

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 角色、提供下载链接或撤销访问。订阅这些事件以保持您的应用程序与每个客户的可访问性同步。
EventDescription
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 合作者移除、许可证密钥禁用、不再发放文件下载 URL。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_files，则会包含 digital_product_delivery。它包含预签名下载 URL，选择性的 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。 Discord、GitHub 或 Notion 订阅者流的 entitlement_grant.created 事件包括一个 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