Chuyển đến nội dung chính

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.

​
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.
Sự KiệnMô Tả
entitlement_grant.createdMột dòng cấp quyền mới đã được tạo. Trạng thái là delivered ngay lập tức đối với các license key, và pending cho mọi tích hợp khác.
entitlement_grant.deliveredQuyền chuyển sang được giao hàng. Khách hàng hiện có quyền truy cập vào nền tảng, tập tin hoặc license key đã được cấp.
entitlement_grant.failedGiao hàng thất bại và không được thử lại. Kiểm tra error_code và error_message.
entitlement_grant.revokedQuyền truy cập đã bị rút lạ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 dòng cấp quyền vừa được chèn. Quyền luôn có một id ổn định từ lúc này, ngay cả khi trạng thái của nó thay đổi. Sử dụng sự kiện này để ghi lại rằng việc thực hiện đang diễn ra. Đối với license keys dòng được chèn trực tiếp với status: "delivered" và delivered_at đã được điền, vì vậy một sự kiện created duy nhất được theo sau mà không có sự thay đổi trạng thái nào nữa trừ khi quyền sau đó bị thu hồi. Đối với mọi tích hợp khác dòng đến với status: "pending". Một sự kiện delivered hoặc failed theo sau khi hoàn thành giao hàng:
  • Tích hợp dựa trên OAuth (Discord, GitHub, Notion) bao gồm một oauth_url mà khách hàng phải truy cập để hoàn tất ủy quyền. Quyền vẫn ở pending cho đến khi khách hàng ủy quyền.
  • Tích hợp trực tiếp qua nền tảng (Telegram, Framer, Digital Files) chỉ ở pending trong một thời gian ngắn trong khi cuộc gọi nền tảng diễn ra, sau đó chuyển đến delivered.

​
entitlement_grant.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”. Trường delivered_at của tải trọng ghi lại khi quá trình giao hàng hoàn tất. Đối với những quyền đã nhận delivered khi tạo, bạn sẽ nhận sự kiện created và delivered liên tiếp.

​
entitlement_grant.failed

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_reasonKí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_changedKế 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).
manualMộ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_disabledKey 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_externalPhí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.

​
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:
  • license_key được bao gồm khi kiểu tích hợp quyền là license_key. Nó chứa key đã tạo, ngày hết hạn và sử dụng kích hoạt.
  • digital_product_delivery được bao gồm khi kiểu tích hợp là digital_files. Nó chứa các URL tải xuống đã ký trước, tùy chọn instructions và tùy chọn external_url.
Đối với tất cả các kiểu tích hợp khác (Discord, GitHub, Telegram, Framer, Notion) cả hai trường là null; cấu hình liên quan được ghi lại trong chính quyền, không phải trong cấp quyền.

​
Payload Ví Dụ

​
License key được giao (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"
  }
}

​
Tệp kỹ thuật số được giao (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"
  }
}

​
Vai trò Discord đượ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": {
    "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"
  }
}

​
Quyền bị thu hồi khi hủy đăng ký (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"
  }
}

​
Giao hàng thất bại (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"
  }
}

​
Mẹo Tích Hợp

  • Chờ entitlement_grant.delivered trước khi mở khóa các tính năng phụ thuộc. Một sự kiện payment.succeeded cho bạn biết tiền đã được giải ngân; nó không cho bạn biết rằng khách hàng đã có repo GitHub hoặc vai trò Discord. Sự kiện delivered là nguồn sự thật cho việc thực hiện.
  • Lập bản đồ revocation_reason đến luồng giữ chân người dùng. Một quyền hồi lại subscription_on_hold thường có nghĩa là thẻ của khách hàng đã thất bại và lần gia hạn tiếp theo sẽ cấp lại quyền. Một quyền hồi lại manual hoặc subscription_cancelled là có chủ ý. Xử lý chúng khác nhau trong thông báo khách hàng.
  • Sử dụng quyền id như là khóa idempotency của bạn. Một quyền duy nhất phát ra nhiều nhất một sự kiện created và nhiều nhất một sự kiện cuối cùng (delivered hoặc failed), và nhiều nhất một sự kiện revoked. Các đợt giao lại từ hệ thống webhook có thể lặp lại các sự kiện; loại bỏ trùng lặp trên cấp quyền id cộng type.
  • Kiểm tra license_key và digital_product_delivery để nhận biết kiểu tích hợp. Bản thân tải trọng quyền không mang kiểu tích hợp, nhưng chính xác một trong các đối tượng con này được điền cho các quyền license-key và tệp kỹ thuật số.
  • Đối với các quyền dựa trên OAuth, hiển thị oauth_url cho khách hàng. Sự kiện entitlement_grant.created cho luồng thuê bao Discord, GitHub hoặc Notion bao gồm một oauth_url và oauth_expires_at. Gửi email nó cho khách hàng hoặc hiển thị trong ứng dụng của bạn để giải phóng việc giao hàng.

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

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

​
id
string
bắt buộc

Unique identifier of the grant.

​
metadata
object
bắt buộc

Arbitrary key-value metadata recorded on the grant.

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