权限授予

权限授予 Webhook 事件

每当客户的权限授予状态发生变化时，这些事件将触发，例如生成许可证密钥、分配 Discord 角色、提供下载链接或撤销访问。订阅这些事件以保持您的应用程序与每个客户的可访问性同步。

事件	描述
`entitlement_grant.created`	已创建新的 grant 行。对于自动履行的 License Key，状态会立即变为 `Delivered`；对于手动履行的 License Key 以及其他所有集成，状态会变为 `Pending`。
`entitlement_grant.delivered`	grant 已转换为已交付状态。客户现在可以访问被授予权限的平台、文件或 License Key。
`entitlement_grant.failed`	交付失败且不会重试。请检查 `error_code` 和 `error_message`。
`entitlement_grant.revoked`	访问权限已被撤销。请检查 `revocation_reason` 以了解原因。

所有四个事件共享相同的 EntitlementGrantResponse 负载，如下模式所述。

事件触发器

entitlement_grant.created

授予行刚刚插入。从此时起，即使状态发生变化，授予始终具有稳定的 id。使用此事件记录履行正在进行中。对于自动履行的 License Key，该行会直接插入，并填充 status: "Delivered" 和 delivered_at，因此单个 created 事件之后不会再有其他状态变更，除非该 grant 随后被撤销。对于手动履行的 License Key（包含 fulfillment_mode: manual 的 entitlement），该行到达时会包含 status: "Pending"，但不包含 license_key 对象——此时还没有 License Key。此事件表示有一个 License Key 正在等待履行；请通过 POST /grants/{grant_id}/license-key 提供 License Key，随后系统会触发 entitlement_grant.delivered。请参阅手动履行。对于其他所有集成，该行到达时会包含 status: "Pending"。交付完成后会触发 delivered 或 failed 事件：

基于 OAuth 的集成（Discord、GitHub、Notion）会包含一个 oauth_url，客户必须访问该链接以完成授权同意。在客户完成授权之前，grant 会保持为 Pending。
平台直连集成（Telegram、Framer、Digital Files）只会在平台调用执行期间短暂处于 Pending，随后转换为 Delivered。

entitlement_grant.delivered

grant 已从 Pending 转换为 Delivered。客户现在可以获得 entitlement 所描述的访问权限。使用此事件在自己的系统中解锁依赖功能，例如配置工作区、发送自定义欢迎邮件，或将 “fulfilled” 标记设为已完成。 payload 的 delivered_at 字段记录了交付完成的时间。对于创建时即处于 Delivered 的 grant，您会连续收到 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` event）。
`subscription_on_hold`	由于续订失败，订阅处于暂停状态（`subscription.on_hold`）。可恢复：重试成功后会重新授予权限。
`SubscriptionPaused`	订阅已暂停（`subscription.paused`）。可恢复：恢复订阅后会重新授予权限。
`subscription_expired`	订阅已达到其期限末尾（`subscription.expired`）。
`plan_changed`	计划已更改；旧权限会在授予新权限之前被撤销（`subscription.plan_changed`）。
`refund`	原始一次性付款已处理退款（`refund.succeeded`）。
`manual`	Merchant 通过 API 或 dashboard 撤销了该权限。手动撤销的权限不会在订阅续订时自动重新授予。
`license_key_disabled`	license-key grant 对应的许可证密钥已被禁用。如果重新启用该密钥，系统会自动重新激活该权限。
`platform_external`	集成的平台端出现了同步偏差（例如，Discord 角色被手动移除、GitHub App 失去了仓库访问权限，或 reconciliation pass 检测到缺失的目标）。在底层平台问题解决之前，该权限不会在订阅续订时自动重新授予。

负载变体

data 字段始终是一个 EntitlementGrantResponse 对象。payload 包含一个 integration_type 字段（例如 license_key、digital_files、discord），因此您可以直接识别 grant 类型。三种集成类型还会附加额外的嵌套对象：

当 integration_type 为 license_key 且已签发 License Key 时，会包含 license_key。其中包含生成的 License Key、到期时间和激活使用情况。对于仍处于 Pending 的手动履行 grant，在您履行该 grant 之前，此对象为 null。
当 integration_type 为 digital_files 时，会包含 digital_product_delivery。其中包含预签名下载 URL、可选的 instructions 以及可选的 external_url。
当 integration_type 为 feature_flag 时，会包含 feature。其中包含 grant 所授予能力的 feature_type 和 feature_id。

对于其他所有集成类型（Discord、GitHub、Telegram、Figma、Framer、Notion），这些嵌套字段均为 null；相关配置记录在 entitlement 本身中，而不是 grant 中。

示例负载

许可证密钥已交付 (`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 的 License Key entitlement 时触发。此时 grant 为 Pending，尚无 license_key 对象——商户必须提供 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 撤销则是有意执行的。请在客户沟通中区别对待。
使用 grant 的 id 作为幂等键。 单个 grant 最多会发出一个 created 事件、一个终止事件（delivered 或 failed），以及一个 revoked 事件。Webhook 系统的重新交付可能会重复事件；请根据 grant 的 id 和 type 进行去重。
读取 integration_type 以识别 grant 类型。 payload 会直接携带 integration_type（例如 license_key、digital_files、discord）。相应的 grant 完成交付后，license_key 和 digital_product_delivery 嵌套对象会被填充；手动履行的 License Key grant 在您履行之前，会保持为 Pending，并带有 integration_type: "license_key" 以及一个为 null 的 license_key。
对于基于 OAuth 的 grant，向客户展示 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.

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.

最后修改于 2026年8月21日

{
  "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`)

集成提示