Trao Quyền

Sự Kiện Webhook Trao Quyền

Các sự kiện này được kích hoạt mỗi khi quyền của khách hàng thay đổi trạng thái, ví dụ khi một license key được tạo, một vai trò Discord được gán, một liên kết tải xuống được cung cấp hoặc quyền truy cập bị từ chối. Đăng ký các sự kiện này để giữ cho ứng dụng của bạn đồng bộ với những gì mỗi khách hàng có thể truy cập.

Event	Description
`entitlement_grant.created`	Một hàng grant mới đã được tạo. Trạng thái là `Delivered` ngay lập tức đối với license keys được fulfillment tự động và feature flags, và `Pending` đối với license keys được fulfillment thủ công và mọi integration khác.
`entitlement_grant.delivered`	Grant chuyển sang trạng thái đã được giao. Khách hàng hiện có quyền truy cập vào platform, file hoặc license key được cấp quyền.
`entitlement_grant.failed`	Delivery thất bại và sẽ không được thử lại. Kiểm tra `error_code` và `error_message`.
`entitlement_grant.revoked`	Quyền truy cập đã bị thu hồi. Kiểm tra `revocation_reason` để hiểu lý do.

Cả bốn sự kiện đều chia sẻ cùng một tải trọng EntitlementGrantResponse được tài liệu hóa trong sơ đồ dưới đây.

Kích Hoạt Sự Kiện

entitlement_grant.created

Một hàng grant đã được chèn. Kể từ thời điểm này, grant luôn có id ổn định, ngay cả khi trạng thái thay đổi. Sử dụng event này để ghi nhận rằng quá trình fulfillment đang diễn ra. Đối với license keys được fulfillment tự động và feature flags, hàng được chèn trực tiếp với status: "Delivered" và delivered_at đã được điền, vì vậy một event created duy nhất sẽ không có thêm thay đổi trạng thái nào, trừ khi grant sau đó bị thu hồi. Đối với license key được fulfillment thủ công (entitlement có fulfillment_mode: manual), row được tạo với status: "Pending" và không có object license_key — chưa có key. Event này báo hiệu rằng một key đang chờ fulfillment; hãy cung cấp key qua POST /grants/{grant_id}/license-key, sau đó event entitlement_grant.delivered sẽ được phát. Xem Manual Fulfillment. Đối với mọi integration khác, row được tạo với status: "Pending". Một event delivered hoặc failed sẽ được phát sau khi delivery hoàn tất:

Các integration dựa trên OAuth (Discord, GitHub, Notion) sử dụng một oauth_url mà khách hàng phải truy cập để hoàn tất việc cấp quyền. Dodo Payments cố gắng tạo URL này khi grant được tạo, vì vậy entitlement_grant.created có thể bao gồm URL này; nếu là null, URL sẽ được điền khi khách hàng bắt đầu accept flow từ Customer Portal. Grant vẫn ở trạng thái Pending cho đến khi khách hàng cấp quyền.
Các integration trực tiếp với platform (Telegram, Framer, Digital Files) chỉ ở trạng thái Pending trong thời gian ngắn khi lời gọi đến platform đang chạy, sau đó chuyển sang Delivered.

Quyền đã chuyển từ pending sang delivered. Khách hàng hiện có quyền truy cập như đã mô tả trong quyền. Sử dụng sự kiện này để mở khóa các tính năng phụ thuộc trong hệ thống của bạn, ví dụ để cung cấp một không gian làm việc, gửi email chào mừng tùy chỉnh hoặc đánh dấu một cờ “đã hoàn thành”. Grant đã chuyển sang Delivered, thường là từ Pending. Khách hàng hiện có quyền truy cập được mô tả trong entitlement. Sử dụng event này để mở khóa các feature phụ thuộc trong hệ thống của bạn, chẳng hạn như provision một workspace, gửi email chào mừng tùy chỉnh hoặc đánh dấu cờ “fulfilled”. Trường delivered_at trong payload ghi nhận thời điểm delivery hoàn tất. delivered được phát bất cứ khi nào trạng thái của một grant hiện có thay đổi thành Delivered: từ Pending, khi một OAuth grant thất bại sau đó thành công, hoặc khi một grant đã bị thu hồi được khôi phục. Grant có trạng thái Delivered ngay khi được tạo, chẳng hạn như license key được fulfillment tự động, chỉ phát created. Giao hàng đã được thử nghiệm nhưng thất bại với lỗi không thể thử lại. Các trường error_code và error_message giải thích lý do thất bại. Nguyên nhân phổ biến bao gồm token OAuth bị thu hồi, quyền nền tảng bị từ chối, hoặc mục tiêu bị thiếu (ví dụ, một guild Discord đã bị xóa).

Xử lý entitlement_grant.failed như một hành động có thể thực hiện. Khách hàng đã thanh toán nhưng không nhận được quyền truy cập. Hiển thị các thất bại cho đội ngũ hỗ trợ của bạn hoặc kích hoạt lại sau khi vấn đề cơ bản được giải quyết.

entitlement_grant.revoked

Quyền truy cập đã bị rút lại ở cấp độ nền tảng: vai trò Discord bị xóa, cộng tác viên GitHub bị xóa, key giấy phép bị vô hiệu hóa, URL tải xuống tệp không còn được cấp phát. Trường revocation_reason ghi lại kích hoạt.

`revocation_reason`	Kích Hoạt
`subscription_cancelled`	Đăng ký của khách hàng đã bị hủy (sự kiện `subscription.cancelled`).
`subscription_on_hold`	Đăng ký đang bị tạm giữ do gia hạn thất bại (`subscription.on_hold`). Có thể khôi phục: một lần thử lại thành công sẽ cấp quyền lại.
`subscription_expired`	Đăng ký đã đạt đến ngày kết thúc nhiệm kỳ (`subscription.expired`).
`plan_changed`	Kế hoạch đã thay đổi; quyền cũ bị thu hồi trước khi cấp quyền mới (`subscription.plan_changed`).
`refund`	Đã xử lý một khoản hoàn tiền cho thanh toán một lần ban đầu (`refund.succeeded`).
`manual`	Một nhà cung cấp hủy bỏ quyền thông qua API hoặc bảng điều khiển. Khi thu hồi thủ công, sẽ không tự động cấp lại khi gia hạn đăng ký.
`license_key_disabled`	Key sau một quyền cấp license-key đã bị vô hiệu hóa. Quyền được kích hoạt lại tự động nếu key được tái kích hoạt.
`platform_external`	Phía nền tảng của một tích hợp không đồng bộ (ví dụ, vai trò Discord bị xóa thủ công, Ứng dụng GitHub mất quyền truy cập kho, hoặc kiểm tra đối chiếu phát hiện thiếu mục tiêu). Quyền sẽ không tự động cấp lại khi gia hạn đăng ký cho đến khi vấn đề nền tảng cơ bản được giải quyết.

`revocation_reason`	Kích hoạt
`subscription_cancelled`	Gói đăng ký của khách hàng đã bị hủy (sự kiện `subscription.cancelled`).
`subscription_on_hold`	Gói đăng ký đang bị tạm giữ do gia hạn không thành công (`subscription.on_hold`). Có thể khôi phục: một lần thử lại thành công sẽ cấp lại quyền.
`subscription_paused`	Gói đăng ký đã bị tạm dừng (`subscription.paused`). Có thể khôi phục: tiếp tục sẽ cấp lại quyền.
`subscription_expired`	Gói đăng ký đã kết thúc thời hạn (`subscription.expired`).
`plan_changed`	Gói đã thay đổi; các quyền cũ bị thu hồi trước khi quyền mới được cấp (`subscription.plan_changed`).
`refund`	Khoản hoàn tiền đã được xử lý cho khoản thanh toán một lần ban đầu (`refund.succeeded`).
`manual`	Merchant đã thu hồi quyền thông qua API hoặc dashboard. Quyền bị thu hồi thủ công sẽ không được tự động cấp lại khi gói đăng ký gia hạn.
`license_key_disabled`	License key đứng sau quyền cấp license key đã bị vô hiệu hóa. Quyền sẽ được tự động kích hoạt lại nếu license key được bật lại.
`platform_external`	Phía nền tảng của một integration đã không còn đồng bộ (ví dụ: một vai trò Discord bị xóa thủ công, GitHub App mất quyền truy cập repository hoặc một lượt đối soát phát hiện target bị thiếu). Quyền sẽ không được tự động cấp lại khi gói đăng ký gia hạn cho đến khi sự cố trên nền tảng cơ sở được khắc phục.

Biến Thể Payload

Trường data luôn là một đối tượng EntitlementGrantResponse. Hai kiểu tích hợp đính kèm thêm các đối tượng con: Trường data luôn là một object EntitlementGrantResponse. Payload chứa một trường integration_type (ví dụ license_key, digital_files, discord) để bạn có thể nhận diện trực tiếp loại grant. Ba loại integration cũng đính kèm các object nested bổ sung:

license_key được bao gồm khi integration_type là license_key và một key đã được cấp. Object này chứa key được tạo, thời hạn hết hạn và thông tin sử dụng activation. Đối với grant được fulfillment thủ công vẫn ở trạng thái Pending, object này là null cho đến khi bạn fulfillment grant.
digital_product_delivery được bao gồm khi integration_type là digital_files. Object này chứa các URL download presigned, instructions tùy chọn và external_url tùy chọn.
feature được bao gồm khi integration_type là feature_flag. Object này chứa feature_type và feature_id của capability được grant cấp.

Đối với tất cả các loại integration khác (Discord, GitHub, Telegram, Figma, Framer, Notion), các field nested này là null; cấu hình liên quan được lưu trong entitlement, không phải trong grant.

Payload Ví Dụ

License key được giao (`entitlement_grant.delivered`)

License Key đã được giao (`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"
  }
}

License Key đang chờ fulfillment thủ công (`entitlement_grant.created`)

Được phát khi customer mua một product có entitlement License Key sử dụng fulfillment_mode: manual. Grant ở trạng thái Pending và chưa có object license_key — merchant phải cung cấp 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"
  }
}

Digital Files đã được giao (`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 Role đã được tạo và đang chờ xử lý (`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"
  }
}

Grant bị thu hồi khi hủy subscription (`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"
  }
}

Delivery thất bại (`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"
  }
}

Mẹo Tích Hợp

Mở khóa các tính năng phụ thuộc khi grant đạt trạng thái Delivered. Một event payment.succeeded cho bạn biết khoản tiền đã được clearing; event này không cho biết khách hàng đã có GitHub repo hoặc Discord role hay chưa. Hãy xử lý entitlement_grant.delivered, đồng thời xử lý entitlement_grant.created cùng với status: "Delivered", vì grant được giao ngay khi tạo sẽ không phát ra event delivered nào.
Ánh xạ revocation_reason vào các retention flow. Việc revoke subscription_on_hold thường có nghĩa là thẻ của khách hàng bị từ chối và lần gia hạn tiếp theo sẽ cấp lại quyền truy cập. Việc revoke manual hoặc subscription_cancelled là có chủ đích. Hãy xử lý chúng khác nhau trong thông điệp gửi khách hàng.
Phát hiện các bản sao bằng header webhook-id, không phải grant id. Một grant phát ra created một lần, nhưng delivered và revoked có thể mỗi loại được phát ra nhiều lần, vì một grant đã bị revoke có thể được khôi phục rồi lại bị revoke. failed cũng không phải lúc nào cũng là trạng thái cuối: một OAuth grant thất bại vẫn có thể được giao. Việc gửi lại từ hệ thống webhook cũng có thể khiến một event bị lặp lại. Bỏ qua các bản lặp dựa trên webhook-id và dùng grant id làm khóa cho các bản ghi grant của riêng bạn.
Đọc integration_type để nhận biết loại grant. Payload chứa trực tiếp integration_type (ví dụ license_key, digital_files, discord). Các object lồng nhau license_key và digital_product_delivery được điền sau khi các grant tương ứng được giao; một license-key grant được hoàn tất thủ công vẫn ở trạng thái Pending với integration_type: "license_key" và một null license_key cho đến khi bạn hoàn tất việc giao.
Đối với các OAuth grant, hiển thị oauth_url cho khách hàng. Event entitlement_grant.created trong các subscriber flow của Discord, GitHub hoặc Notion có thể bao gồm một oauth_url và oauth_expires_at. Nếu là null, hãy chờ event tiếp theo hoặc hướng khách hàng đến Customer Portal. Gửi URL qua email cho khách hàng hoặc hiển thị URL trong app của bạn để tiếp tục quá trình giao.

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

brand_id

string

bắt buộc

Brand id this grant belongs to.

business_id

string

bắt buộc

Identifier of the business that owns the grant.

created_at

string<date-time>

bắt buộc

Timestamp when the grant was created.

customer_id

string

bắt buộc

Identifier of the customer the grant was issued to.

entitlement_id

string

bắt buộc

Identifier of the entitlement this grant was issued from.

string

bắt buộc

Unique identifier of the grant.

integration_type

enum<string>

bắt buộc

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

Tùy chọn có sẵn:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

bắt buộc

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

bắt buộc

Lifecycle status of the grant.

Tùy chọn có sẵn:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

bắt buộc

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Sự Kiện Webhook Trao Quyền

Kích Hoạt Sự Kiện

entitlement_grant.created

entitlement_grant.revoked

Biến Thể Payload

Payload Ví Dụ

License key được giao (`entitlement_grant.delivered`)

License Key đã được giao (`entitlement_grant.delivered`)

License Key đang chờ fulfillment thủ công (`entitlement_grant.created`)

Digital Files đã được giao (`entitlement_grant.delivered`)

Discord Role đã được tạo và đang chờ xử lý (`entitlement_grant.created`)

Grant bị thu hồi khi hủy subscription (`entitlement_grant.revoked`)

Delivery thất bại (`entitlement_grant.failed`)

Mẹo Tích Hợp

​Sự Kiện Webhook Trao Quyền

​Kích Hoạt Sự Kiện

​entitlement_grant.created

​entitlement_grant.revoked

​Biến Thể Payload

​Payload Ví Dụ

​License key được giao (entitlement_grant.delivered)

​License Key đã được giao (entitlement_grant.delivered)

​License Key đang chờ fulfillment thủ công (entitlement_grant.created)

​Digital Files đã được giao (entitlement_grant.delivered)

​Discord Role đã được tạo và đang chờ xử lý (entitlement_grant.created)

​Grant bị thu hồi khi hủy subscription (entitlement_grant.revoked)

​Delivery thất bại (entitlement_grant.failed)

​Mẹo Tích Hợp

Sự Kiện Webhook Trao Quyền

Kích Hoạt Sự Kiện

entitlement_grant.created

entitlement_grant.revoked

Biến Thể Payload

Payload Ví Dụ

License key được giao (`entitlement_grant.delivered`)

License Key đã được giao (`entitlement_grant.delivered`)

License Key đang chờ fulfillment thủ công (`entitlement_grant.created`)

Digital Files đã được giao (`entitlement_grant.delivered`)

Discord Role đã được tạo và đang chờ xử lý (`entitlement_grant.created`)

Grant bị thu hồi khi hủy subscription (`entitlement_grant.revoked`)

Delivery thất bại (`entitlement_grant.failed`)

Mẹo Tích Hợp