자격 부여

자격 부여 웹훅 이벤트

고객의 자격 부여가 상태를 변경할 때마다 예를 들어 라이선스 키가 생성되거나, Discord 역할이 할당되거나, 다운로드 링크가 제공되거나, 액세스가 취소될 때 트리거됩니다. 이러한 이벤트에 구독하여 각 고객이 액세스할 수 있는 내용을 지속적으로 동기화하세요.

이벤트	설명
`entitlement_grant.created`	새 grant 행이 생성되었습니다. 자동으로 처리되는 라이선스 키와 feature flags의 경우 상태는 즉시 `Delivered`이며, 수동으로 처리되는 라이선스 키와 그 외 모든 통합의 경우 `Pending`입니다.
`entitlement_grant.delivered`	grant가 delivered 상태로 전환됩니다. 이제 고객은 권한이 부여된 플랫폼, 파일 또는 라이선스 키에 액세스할 수 있습니다.
`entitlement_grant.failed`	전달에 실패했으며 재시도되지 않습니다. `error_code` 및 `error_message`를 확인하세요.
`entitlement_grant.revoked`	액세스 권한이 철회되었습니다. 이유를 파악하려면 `revocation_reason`를 확인하세요.

모든 네 개의 이벤트는 아래 스키마에 문서화된 동일한 EntitlementGrantResponse 페이로드를 공유합니다.

이벤트 트리거

entitlement_grant.created

grant 행이 삽입되었습니다. 이 시점부터 grant에는 상태가 변경되더라도 항상 안정적인 id가 있습니다. 이 이벤트를 사용해 fulfillment가 진행 중임을 기록하세요. 자동으로 처리되는 라이선스 키와 feature flags의 경우 행이 status: "Delivered" 및 delivered_at가 채워진 상태로 직접 삽입되므로, 하나의 created 이벤트 이후에는 grant가 나중에 철회되지 않는 한 추가 상태 변경이 발생하지 않습니다. manually-fulfilled license keys(fulfillment_mode: manual가 있는 entitlement)의 경우 행이 status: "Pending" 상태로 도착하고 license_key 객체는 없습니다. 아직 key가 발급되지 않은 것입니다. 이 이벤트는 key가 fulfillment를 기다리고 있다는 신호입니다. POST /grants/{grant_id}/license-key를 통해 key를 제공하면 entitlement_grant.delivered가 발생합니다. Manual Fulfillment를 참조하세요. 그 외 모든 integration의 경우 행이 status: "Pending" 상태로 도착합니다. delivery가 완료되면 delivered 또는 failed 이벤트가 이어집니다:

OAuth 기반 통합(Discord, GitHub, Notion)은 고객이 동의를 완료하기 위해 방문해야 하는 oauth_url를 사용합니다. Dodo Payments는 grant가 생성될 때 이를 생성하려고 하므로, entitlement_grant.created에 이것이 포함될 수 있습니다. null인 경우에는 고객이 Customer Portal에서 accept flow를 시작할 때 입력됩니다. 고객이 승인할 때까지 grant는 Pending 상태로 유지됩니다.
Platform-direct 통합(Telegram, Framer, Digital Files)은 platform call이 실행되는 동안에만 잠시 Pending 상태에 있다가 Delivered 상태로 전환됩니다.

부여는 pending에서 delivered로 전환되었습니다. 이제 고객은 자격 부여된 액세스를 받았습니다. 이 이벤트를 사용하여 작업 공간을 제공하거나, 맞춤 환영 이메일을 보내거나, “이행 완료” 플래그를 표시하는 등의 종속 기능을 잠금 해제하세요. grant가 일반적으로 Pending에서 Delivered로 전환되었습니다. 이제 고객은 entitlement에 설명된 액세스 권한을 갖습니다. 이 이벤트를 사용해 자체 시스템에서 종속 기능을 활성화하세요. 예를 들어 workspace를 프로비저닝하거나, 맞춤 환영 이메일을 보내거나, “fulfilled” 플래그를 설정할 수 있습니다. payload의 delivered_at 필드에는 전달이 완료된 시점이 기록됩니다. delivered는 기존 grant의 상태가 Delivered로 변경될 때마다 발생합니다. 여기에는 Pending에서 변경되는 경우, 실패한 OAuth grant가 나중에 성공하는 경우, 철회된 grant가 복원되는 경우가 포함됩니다. 자동으로 처리되는 라이선스 키처럼 생성 시 Delivered 상태로 도착하는 grant는 created만 발생시킵니다. 전달이 시도되었으나 다시 시도할 수 없는 오류로 실패했습니다. 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 앱이 리포지토리 접근 권한 상실, 혹은 대상을 찾을 수 없는 조정 통과). 근본적인 플랫폼 문제가 해결될 때까지 구독 갱신 시 부여가 자동 재부여되지 않습니다.

`revocation_reason`	트리거
`subscription_cancelled`	고객의 구독이 취소되었습니다(`subscription.cancelled` 이벤트).
`subscription_on_hold`	갱신 실패로 인해 구독이 보류 중입니다(`subscription.on_hold`). 복구 가능: 성공적으로 재시도하면 권한이 다시 부여됩니다.
`subscription_paused`	구독이 일시 중지되었습니다(`subscription.paused`). 복구 가능: 재개하면 권한이 다시 부여됩니다.
`subscription_expired`	구독 기간이 종료되었습니다(`subscription.expired`).
`plan_changed`	플랜이 변경되었습니다. 새 권한이 부여되기 전에 기존 권한이 취소됩니다(`subscription.plan_changed`).
`refund`	최초 일회성 결제에 대한 환불이 처리되었습니다(`refund.succeeded`).
`manual`	판매자가 API 또는 대시보드를 통해 권한 부여를 취소했습니다. 수동으로 취소된 권한은 구독 갱신 시 자동으로 다시 부여되지 않습니다.
`license_key_disabled`	라이선스 키 권한 부여에 사용된 라이선스 키가 비활성화되었습니다. 키가 다시 활성화되면 권한이 자동으로 재활성화됩니다.
`platform_external`	통합의 플랫폼 측 동기화가 어긋났습니다(예: Discord 역할이 수동으로 제거되었거나, GitHub App이 저장소 액세스 권한을 잃었거나, 조정 과정에서 대상이 누락된 것으로 감지된 경우). 기본 플랫폼 문제가 해결될 때까지 구독 갱신 시 권한이 자동으로 다시 부여되지 않습니다.

페이로드 변형

data 필드는 항상 EntitlementGrantResponse 객체입니다. 두 가지 통합 유형은 추가 중첩 객체를 첨부합니다: data field는 항상 EntitlementGrantResponse object입니다. payload에는 integration_type field가 포함되어 있어(예: license_key, digital_files, discord) grant type을 직접 식별할 수 있습니다. 세 가지 integration type에는 추가 중첩 object도 포함됩니다:

**license_key**는 integration_type가 license_key이고 key가 발급된 경우 포함됩니다. 생성된 key, 만료일 및 activation usage가 들어 있습니다. 아직 Pending 상태인 manually-fulfilled grant의 경우 grant를 fulfill할 때까지 이 object는 null입니다.
**digital_product_delivery**는 integration_type가 digital_files인 경우 포함됩니다. presigned download URL, 선택적 instructions 및 선택적 external_url가 들어 있습니다.
**feature**는 integration_type가 feature_flag인 경우 포함됩니다. grant가 부여하는 capability의 feature_type 및 feature_id가 들어 있습니다.

그 외 모든 integration type(Discord, GitHub, Telegram, Figma, Framer, Notion)에서는 이러한 중첩 field가 null입니다. 관련 configuration은 grant가 아니라 entitlement 자체에 기록됩니다.

샘플 페이로드

라이선스 키 전송 완료 (`entitlement_grant.delivered`)

라이선스 키 전달됨 (`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"
  }
}

라이선스 키 수동 처리 대기 중 (`entitlement_grant.created`)

customer가 fulfillment_mode: manual를 사용하는 License Key entitlement가 포함된 product를 구매할 때 발생합니다. grant는 아직 license_key object가 없는 Pending 상태이며, merchant가 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"
  }
}

디지털 파일 전달됨 (`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 역할 생성 및 대기 중 (`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 철회됨 (`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"
  }
}

전달 실패 (`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"
  }
}

통합 팁

grant가 Delivered에 도달하면 종속 기능을 활성화하세요. payment.succeeded event는 대금이 결제되었음을 알려주지만, 고객이 아직 GitHub repo 또는 Discord role을 받았다는 의미는 아닙니다. entitlement_grant.delivered를 처리하고, entitlement_grant.created도 status: "Delivered"와 함께 처리하세요. 생성 시 전달되는 grant는 delivered event를 발생시키지 않기 때문입니다.
revocation_reason를 retention flow에 매핑하세요. subscription_on_hold revoke는 일반적으로 고객의 카드 결제가 실패했으며 다음 renewal에서 액세스 권한이 다시 부여된다는 의미입니다. manual 또는 subscription_cancelled revoke는 의도적인 동작입니다. 고객 메시지에서 이들을 다르게 처리하세요.
grant id가 아니라 webhook-id header를 사용해 중복을 감지하세요. grant는 created를 한 번 emit하지만, delivered와 revoked는 각각 여러 번 발생할 수 있습니다. revoke된 grant가 복원되었다가 다시 revoke될 수 있기 때문입니다. failed도 항상 최종 상태인 것은 아닙니다. 실패한 OAuth grant도 전달될 수 있습니다. webhook system의 재전달로 인해 event가 반복될 수도 있습니다. webhook-id를 기준으로 반복 항목을 건너뛰고, 자체 grant record의 key에는 grant id를 사용하세요.
integration_type를 읽어 grant type을 확인하세요. payload에는 integration_type가 직접 포함됩니다(예: license_key, digital_files, discord). license_key 및 digital_product_delivery nested object는 해당 grant가 전달되면 채워집니다. 수동으로 fulfill하는 license-key grant는 fulfill할 때까지 Pending 상태로 유지되며, integration_type: "license_key" 및 null license_key를 포함합니다.
OAuth 기반 grant의 경우 oauth_url를 고객에게 표시하세요. Discord, GitHub 또는 Notion subscriber flow의 entitlement_grant.created event에는 oauth_url 및 oauth_expires_at가 포함될 수 있습니다. null인 경우 다음 event를 기다리거나 고객을 Customer Portal로 안내하세요. 고객에게 URL을 이메일로 보내거나 앱에 표시하여 delivery를 진행할 수 있도록 하세요.

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

자격 부여 웹훅 이벤트

이벤트 트리거

entitlement_grant.created

entitlement_grant.revoked

페이로드 변형

샘플 페이로드

라이선스 키 전송 완료 (`entitlement_grant.delivered`)

라이선스 키 전달됨 (`entitlement_grant.delivered`)

라이선스 키 수동 처리 대기 중 (`entitlement_grant.created`)

디지털 파일 전달됨 (`entitlement_grant.delivered`)

Discord 역할 생성 및 대기 중 (`entitlement_grant.created`)

구독 취소로 grant 철회됨 (`entitlement_grant.revoked`)

전달 실패 (`entitlement_grant.failed`)

통합 팁

​자격 부여 웹훅 이벤트

​이벤트 트리거

​entitlement_grant.created

​entitlement_grant.revoked

​페이로드 변형

​샘플 페이로드

​라이선스 키 전송 완료 (entitlement_grant.delivered)

​라이선스 키 전달됨 (entitlement_grant.delivered)

​라이선스 키 수동 처리 대기 중 (entitlement_grant.created)

​디지털 파일 전달됨 (entitlement_grant.delivered)

​Discord 역할 생성 및 대기 중 (entitlement_grant.created)

​구독 취소로 grant 철회됨 (entitlement_grant.revoked)

​전달 실패 (entitlement_grant.failed)

​통합 팁

자격 부여 웹훅 이벤트

이벤트 트리거

entitlement_grant.created

entitlement_grant.revoked

페이로드 변형

샘플 페이로드

라이선스 키 전송 완료 (`entitlement_grant.delivered`)

라이선스 키 전달됨 (`entitlement_grant.delivered`)

라이선스 키 수동 처리 대기 중 (`entitlement_grant.created`)

디지털 파일 전달됨 (`entitlement_grant.delivered`)

Discord 역할 생성 및 대기 중 (`entitlement_grant.created`)

구독 취소로 grant 철회됨 (`entitlement_grant.revoked`)

전달 실패 (`entitlement_grant.failed`)

통합 팁