権利付与

権利付与ウェブフックイベント

これらのイベントは、顧客の権利付与の状態が変化するたびに発生します。例えば、ライセンスキーが生成された時、Discordの役割が割り当てられた時、ダウンロードリンクが提供された時、またはアクセスが取り消された時です。これらのイベントを購読して、各顧客がアクセスできる内容とアプリケーションを同期させましょう。

Event	Description
`entitlement_grant.created`	新しい grant の行が作成されました。ステータスは、自動で fulfillment される license key と feature flag の場合は直ちに `Delivered` となり、手動で fulfillment される license key とその他すべての integration の場合は `Pending` となります。
`entitlement_grant.delivered`	grant が delivered に移行しました。customer は、entitled された platform、file、または license key にアクセスできるようになりました。
`entitlement_grant.failed`	delivery に失敗し、再試行されていません。`error_code` と `error_message` を確認してください。
`entitlement_grant.revoked`	access が取り消されました。理由を確認するには `revocation_reason` を確認してください。

すべての4つのイベントは、以下のスキーマに記載されている同じ EntitlementGrantResponse ペイロードを共有しています。

イベントトリガー

entitlement_grant.created

grant の行が挿入されました。この時点以降、ステータスが変わっても grant には常に固定の id があります。この event を使用して、fulfillment が進行中であることを記録してください。 auto-fulfilled license keys と feature flags の場合、行は status: "Delivered" と delivered_at が入力された状態で直接挿入されます。そのため、単一の created event の後、grant が後で revoked されない限り、以降の state change は発生しません。 manually-fulfilled license keys（fulfillment_mode: manual を持つ entitlements）の場合、行は status: "Pending" とともに作成され、license_key object はありません — まだ key が存在しないためです。この event は、key が fulfillment 待ちであることを示します。POST /grants/{grant_id}/license-key で key を提供すると、entitlement_grant.delivered が発生します。Manual Fulfillment を参照してください。 その他すべての integration の場合、行は status: "Pending" とともに作成されます。delivery が完了すると、delivered または failed event が続いて発生します。

OAuthベースのintegration（Discord、GitHub、Notion）では、顧客がconsentを完了するためにアクセスする必要があるoauth_urlを使用します。Dodo Paymentsはgrantの作成時にこれを作成しようとするため、entitlement_grant.createdに含まれている場合があります。nullの場合は、顧客がCustomer Portalからaccept flowを開始した時点で入力されます。顧客が承認するまで、grantはPendingのままです。
Platform-direct integration（Telegram、Framer、Digital Files）は、platform callの実行中のみ短時間Pendingに置かれ、その後Deliveredに移行します。

付与が pending から delivered へ移行しました。顧客は権利で示されるアクセスを現在持っています。このイベントを使用して、独自のシステム内で依存機能を解除するために使用します。例えば、ワークスペースのプロビジョニングやカスタムウェルカムメールの送信、「fulfilled」フラグの設定などです。 grant が Delivered に移行しました。通常は Pending からの移行です。customer は entitlement に記載された access を利用できるようになりました。この event を使用して、独自の system で依存する feature のロックを解除してください。たとえば、workspace の provision、custom welcome email の送信、または「fulfilled」flag の設定などに利用できます。 payload の delivered_at field には、delivery が完了した時刻が記録されます。delivered は、既存の grant の status が Delivered に変わるたびに発生します。Pending からの移行、失敗した OAuth grant が後から成功した場合、または revoked された grant が復元された場合が該当します。auto-fulfilled license key のように、作成時に 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`	merchant が API またはダッシュボードを介して付与を取り消した。手動で取り消された付与は、サブスクリプションの更新時に自動的に再付与されません。
`license_key_disabled`	license-key grant の基盤となるライセンスキーが無効化された。キーが再度有効化されると、付与は自動的に再有効化されます。
`platform_external`	統合のプラットフォーム側で同期ずれが発生した（たとえば、Discord のロールが手動で削除された、GitHub App がリポジトリへのアクセス権を失った、または照合処理で対象の欠落が検出された）。基盤となるプラットフォームの問題が解決されるまで、サブスクリプションの更新時に付与が自動的に再付与されることはありません。

ペイロードバリアント

data フィールドは常に EntitlementGrantResponse オブジェクトです。2つの統合タイプが追加のネストオブジェクトを含みます： data field は常に EntitlementGrantResponse object です。payload には integration_type field（例: license_key、digital_files、discord）が含まれるため、grant type を直接識別できます。3 種類の integration では、さらに nested object も付加されます。

license_key は、integration_type が license_key であり、かつ key が発行済みの場合に含まれます。生成された key、expiry、activation usage が含まれます。まだ Pending の manually-fulfilled grant では、grant を fulfill するまでこの object は null です。
digital_product_delivery は、integration_type が digital_files の場合に含まれます。presigned download URL、optional な instructions、optional な external_url が含まれます。
feature は、integration_type が feature_flag の場合に含まれます。grant によって付与された capability の feature_type と feature_id が含まれます。

その他すべての integration type（Discord、GitHub、Telegram、Figma、Framer、Notion）では、これらの nested field は null です。該当する configuration は grant ではなく entitlement 自体に記録されます。

サンプルペイロード

ライセンスキー配送（`entitlement_grant.delivered`）

License Key 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"
  }
}

License Key Pending Manual Fulfillment (`entitlement_grant.created`)

customer が、License Key entitlement に fulfillment_mode: manual を使用する product を購入したときに発生します。grant は Pending で、license_key object はまだありません — 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"
  }
}

Digital Files Delivered (`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 Created and Pending (`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 Revoked on Subscription Cancellation (`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 Failed (`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"とともに処理してください。作成時にdeliveryされるgrantでは、delivered eventが発生しないためです。
revocation_reasonをretention flowにマッピングします。 subscription_on_hold revokeは通常、顧客のカード決済に失敗し、次回のrenewalでアクセスが再付与されることを意味します。manualまたはsubscription_cancelled revokeは意図的なものです。顧客へのメッセージでは、これらを区別して扱ってください。
grantのidではなく、webhook-id headerで重複を検出します。 grantはcreatedを1回だけ発行しますが、deliveredとrevokedはそれぞれ複数回発生する可能性があります。revokeされたgrantは復元後に再度revokeされることがあるためです。failedも常に最終状態とは限りません。OAuth grantが失敗してもdeliveryされる場合があります。Webhook systemからの再deliveryによって、同じeventが繰り返されることもあります。webhook-idで重複をスキップし、自身のgrant recordではgrant idをキーにしてください。
integration_typeを読み取り、grant typeを認識します。 payloadにはintegration_typeが直接含まれます（例：license_key、digital_files、discord）。license_keyおよびdigital_product_deliveryのnested objectは、それぞれのgrantがdeliveryされると入力されます。手動でfulfillするlicense-key grantは、fulfillするまでintegration_type: "license_key"およびnull license_keyを伴うPendingのままです。
OAuthベースのgrantでは、oauth_urlを顧客に提示します。 Discord、GitHub、またはNotionのsubscriber flowにおけるentitlement_grant.created eventには、oauth_urlとoauth_expires_atが含まれる場合があります。nullの場合は、後続のeventを待つか、顧客をCustomer Portalに案内してください。deliveryを解除するため、URLを顧客にメールで送信するか、アプリに表示します。

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`）

License Key Delivered (`entitlement_grant.delivered`)

License Key Pending Manual Fulfillment (`entitlement_grant.created`)

Digital Files Delivered (`entitlement_grant.delivered`)

Discord Role Created and Pending (`entitlement_grant.created`)

Grant Revoked on Subscription Cancellation (`entitlement_grant.revoked`)

Delivery Failed (`entitlement_grant.failed`)

統合のヒント

​権利付与ウェブフックイベント

​イベントトリガー

​entitlement_grant.created

​entitlement_grant.revoked

​ペイロードバリアント

​サンプルペイロード

​ライセンスキー配送（entitlement_grant.delivered）

​License Key Delivered (entitlement_grant.delivered)

​License Key Pending Manual Fulfillment (entitlement_grant.created)

​Digital Files Delivered (entitlement_grant.delivered)

​Discord Role Created and Pending (entitlement_grant.created)

​Grant Revoked on Subscription Cancellation (entitlement_grant.revoked)

​Delivery Failed (entitlement_grant.failed)

​統合のヒント

権利付与ウェブフックイベント

イベントトリガー

entitlement_grant.created

entitlement_grant.revoked

ペイロードバリアント

サンプルペイロード

ライセンスキー配送（`entitlement_grant.delivered`）

License Key Delivered (`entitlement_grant.delivered`)

License Key Pending Manual Fulfillment (`entitlement_grant.created`)

Digital Files Delivered (`entitlement_grant.delivered`)

Discord Role Created and Pending (`entitlement_grant.created`)

Grant Revoked on Subscription Cancellation (`entitlement_grant.revoked`)

Delivery Failed (`entitlement_grant.failed`)

統合のヒント