権利付与

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

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

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

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

イベントトリガー

entitlement_grant.created

付与行が挿入されました。この時点から、たとえそのステータスが変わっても、付与には安定した id があります。このイベントを使って、履行が進行中であることを記録します。 auto-fulfilled license keys の場合、行は status: "Delivered" と delivered_at が設定された状態で直接挿入されるため、単一の created event の後、grant が後から revoke されない限り、それ以上の 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-based integrations（Discord、GitHub、Notion）には、customer が consent を完了するためにアクセスする必要がある oauth_url が含まれます。customer が authorize するまで、grant は Pending のままです。
Platform-direct integrations（Telegram、Framer、Digital Files）は、platform call の実行中だけ短時間 Pending に留まり、その後 Delivered に移行します。

付与が pending から delivered へ移行しました。顧客は権利で示されるアクセスを現在持っています。このイベントを使用して、独自のシステム内で依存機能を解除するために使用します。例えば、ワークスペースのプロビジョニングやカスタムウェルカムメールの送信、「fulfilled」フラグの設定などです。 grant が Pending から Delivered に遷移しました。customer は entitlement に記載された access を利用できるようになりました。この event を使用して、自社 system の dependent features を有効化してください。たとえば、workspace の provision、custom welcome email の送信、または「fulfilled」flag の設定などに利用できます。 payload の delivered_at field には、delivery が完了した時刻が記録されます。作成時に Delivered となった grant については、created event と delivered event を連続して受け取ります。配信が試行され、再試行不可能なエラーで失敗しました。フィールド 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`）。復旧可能：再試行が成功すると、権限が再付与されます。
`SubscriptionPaused`	サブスクリプションが一時停止された（`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`）

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

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": null,
    "created_at": "2026-05-01T10:24:00Z",
    "updated_at": "2026-05-01T10:24:00Z"
  }
}

サブスクリプションキャンセルで付与が取り消されました（`entitlement_grant.revoked`）

{
  "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"
  }
}

配送失敗（`entitlement_grant.failed`）

{
  "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"
  }
}

{
  "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.delivered を待ちます。 payment.succeeded イベントはお金がクリアされたことを伝えますが、顧客がGitHubリポジトリやDiscord役割をまだ持っていないことを伝えません。delivered イベントは、履行の真実の情報源です。
revocation_reason を保持フローにマッピングします。 subscription_on_hold の取り消しは通常、顧客のカードが失敗し、次の更新が再付与することを意味します。manual または subscription_cancelled の取り消しは意図的です。顧客メッセージングで異なる扱いをしてください。
付与 id を冪等性キーとして使用します。 単一の付与は最大で1つの created イベント、最大で1つのターミナルイベント（delivered または failed）、最大で1つの revoked イベントを発します。ウェブフックシステムからの再配信はイベントを繰り返することがあります；付与の id と type で重複を排除してください。
license_key と digital_product_delivery を検査して統合タイプを認識します。 付与ペイロード自体は統合タイプを保持しませんが、ライセンスキーおよびデジタルファイルの権利に対してこれらのネストされたオブジェクトのどちらか1つが含まれています。
OAuthベースの付与の場合、oauth_url を顧客に表示します。 Discord、GitHub、またはNotionのサブスクリバーフローのentitlement_grant.created イベントには、oauth_url と oauth_expires_at が含まれます。お客様にメールしたり、アプリ内に表示して配信を解除してください。

{
  "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"
  }
}

統合のヒント

dependent features を有効化する前に entitlement_grant.delivered を待機してください。 payment.succeeded event は支払いが確定したことを示しますが、customer がまだ GitHub repo や Discord role を利用できることを示すものではありません。fulfillment の source of truth は delivered event です。
revocation_reason を retention flow に対応付けてください。 subscription_on_hold revoke は通常、customer の card が失敗し、次回 renewal で access が再付与されることを意味します。manual または subscription_cancelled revoke は意図的なものです。customer messaging では両者を区別して扱ってください。
grant の id を idempotency key として使用してください。 1 つの grant から発生する created event は最大 1 件、terminal event（delivered または failed）は最大 1 件、revoked event も最大 1 件です。webhook system からの再 delivery により event が重複する可能性があるため、grant の id と type の組み合わせで重複排除してください。
integration_type を読み取り、grant type を識別してください。 payload には integration_type が直接含まれます（例: license_key、digital_files、discord）。license_key と digital_product_delivery の nested object は、それぞれの grant が delivered されると設定されます。manually-fulfilled license-key grant は、fulfill するまで integration_type: "license_key" と null の license_key を伴った Pending のままです。
OAuth-based grant では、oauth_url を customer に提示してください。 Discord、GitHub、Notion の subscriber flow における entitlement_grant.created event には、oauth_url と oauth_expires_at が含まれます。customer に email で送信するか、app に表示して 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.

最終更新日 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

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

イベントトリガー

entitlement_grant.created

entitlement_grant.revoked

ペイロードバリアント

サンプルペイロード

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

サブスクリプションキャンセルで付与が取り消されました（`entitlement_grant.revoked`）

配送失敗（`entitlement_grant.failed`）

統合のヒント

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

​イベントトリガー

​entitlement_grant.created

​entitlement_grant.revoked

​ペイロードバリアント

​サンプルペイロード

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

​サブスクリプションキャンセルで付与が取り消されました（entitlement_grant.revoked）

​配送失敗（entitlement_grant.failed）

​統合のヒント

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

イベントトリガー

entitlement_grant.created

entitlement_grant.revoked

ペイロードバリアント

サンプルペイロード

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

サブスクリプションキャンセルで付与が取り消されました（`entitlement_grant.revoked`）

配送失敗（`entitlement_grant.failed`）

統合のヒント