Entitlement Grant

Entitlement Grant Webhook Events

Event ini terjadi setiap kali status pemberian hak istimewa pelanggan berubah, misalnya ketika sebuah kunci lisensi dihasilkan, peran Discord diberikan, tautan unduhan disediakan, atau akses dicabut. Berlangganan ke event-event ini untuk menjaga aplikasi Anda tetap sinkron dengan apa yang dapat diakses oleh setiap pelanggan.

Event	Deskripsi
`entitlement_grant.created`	Baris grant baru dibuat. Statusnya adalah `Delivered` secara langsung untuk license key yang dipenuhi otomatis dan feature flag, serta `Pending` untuk license key yang dipenuhi secara manual dan setiap integrasi lainnya.
`entitlement_grant.delivered`	Grant beralih ke status delivered. Customer kini memiliki akses ke platform, file, atau license key yang menjadi haknya.
`entitlement_grant.failed`	Pengiriman gagal dan tidak akan dicoba lagi. Periksa `error_code` dan `error_message`.
`entitlement_grant.revoked`	Akses telah dicabut. Periksa `revocation_reason` untuk memahami alasannya.

Keempat event tersebut memiliki payload EntitlementGrantResponse yang sama seperti yang didokumentasikan dalam skema di bawah.

Pemicu Event

entitlement_grant.created

Baris grant telah disisipkan. Sejak saat ini, grant selalu memiliki id yang stabil, meskipun statusnya berubah. Gunakan event ini untuk mencatat bahwa proses fulfillment sedang berlangsung. Untuk license key yang dipenuhi otomatis dan feature flag, baris tersebut langsung disisipkan dengan status: "Delivered" dan delivered_at yang telah diisi, sehingga satu event created tidak diikuti perubahan status lebih lanjut, kecuali grant tersebut nantinya dicabut. Untuk license key yang dipenuhi secara manual (entitlements dengan fulfillment_mode: manual), baris masuk dengan status: "Pending" dan tanpa objek license_key — belum ada key. Event ini menandakan bahwa key sedang menunggu pemenuhan; berikan key tersebut melalui POST /grants/{grant_id}/license-key, yang kemudian memicu entitlement_grant.delivered. Lihat Manual Fulfillment. Untuk setiap integrasi lainnya, baris masuk dengan status: "Pending". Event delivered atau failed muncul setelah pengiriman selesai:

Integrasi berbasis OAuth (Discord, GitHub, Notion) menggunakan oauth_url yang harus dikunjungi pelanggan untuk menyelesaikan persetujuan. Dodo Payments mencoba membuatnya saat grant dibuat, sehingga entitlement_grant.created dapat menyertakannya; jika null, nilainya diisi saat pelanggan memulai alur penerimaan dari Customer Portal. Grant tetap Pending hingga pelanggan memberikan otorisasi.
Integrasi langsung platform (Telegram, Framer, Digital Files) hanya berada dalam Pending sebentar saat panggilan platform berjalan, lalu berpindah ke Delivered.

Pemberian berpindah dari pending ke delivered. Pelanggan sekarang memiliki akses seperti yang dijelaskan oleh pemberian tersebut. Gunakan event ini untuk membuka fitur bergantung dalam sistem Anda sendiri, misalnya untuk menyediakan workspace, mengirim email sambutan khusus, atau menandai “fulfilled”. Grant beralih ke Delivered, biasanya dari Pending. Customer kini memiliki akses yang dijelaskan oleh entitlement tersebut. Gunakan event ini untuk membuka fitur yang bergantung pada grant di sistem Anda sendiri, misalnya menyediakan workspace, mengirim email sambutan khusus, atau menandai flag “fulfilled”. Field delivered_at dalam payload mencatat kapan pengiriman selesai. delivered dipicu setiap kali status grant yang sudah ada berubah menjadi Delivered: dari Pending, saat grant OAuth yang gagal kemudian berhasil, atau saat grant yang dicabut dipulihkan. Grant yang tiba dalam status Delivered saat dibuat, seperti license key yang dipenuhi otomatis, hanya memicu created. Pengiriman dicoba dan gagal dengan kesalahan yang tidak dapat dicoba ulang. Field error_code dan error_message menjelaskan kegagalan. Penyebab umum termasuk token OAuth dicabut, izin platform ditolak, atau target yang hilang (misalnya, komunitas Discord yang dihapus).

Perlakukan entitlement_grant.failed sebagai tindakan yang dapat dilakukan. Pelanggan membayar tetapi tidak mendapatkan akses. Tampilkan kegagalan kepada tim dukungan Anda atau picu pemberian kembali setelah masalah mendasar teratasi.

entitlement_grant.revoked

Akses ditarik di tingkat platform: peran Discord dihapus, kolaborator GitHub dihapus, kunci lisensi dinonaktifkan, URL unduhan file tidak lagi diterbitkan. Field revocation_reason mencatat pemicu.

`revocation_reason`	Pemicu
`subscription_cancelled`	Langganan pelanggan dibatalkan (`subscription.cancelled` event).
`subscription_on_hold`	Langganan ditangguhkan karena gagal perpanjangan (`subscription.on_hold`). Dapat dipulihkan: percobaan ulang yang berhasil menghasilkan pemberian kembali.
`subscription_expired`	Langganan mencapai akhir masa berlakunya (`subscription.expired`).
`plan_changed`	Paket diubah; pemberian lama dicabut sebelum yang baru dikeluarkan (`subscription.plan_changed`).
`refund`	Sebuah pengembalian diproses untuk pembayaran satu kali asli (`refund.succeeded`).
`manual`	Seorang pedagang mencabut pemberian melalui API atau dasbor. Pencabutan manual tidak secara otomatis diberikan kembali pada pembaruan langganan.
`license_key_disabled`	Kunci lisensi di belakang pemberian kunci-lisensi dinonaktifkan. Pemberian diaktifkan kembali secara otomatis jika kunci diaktifkan kembali.
`platform_external`	Sisi platform dari integrasi tidak sinkron (misalnya, sebuah peran Discord dihapus secara manual, Aplikasi GitHub kehilangan akses repository, atau penelusuran rekonsiliasi mendeteksi target yang hilang). Pemberian tidak diberikan kembali secara otomatis pada pembaruan langganan hingga masalah platform yang mendasar teratasi.

`revocation_reason`	Pemicu
`subscription_cancelled`	Langganan pelanggan dibatalkan (peristiwa `subscription.cancelled`).
`subscription_on_hold`	Langganan ditangguhkan karena perpanjangan yang gagal (`subscription.on_hold`). Dapat dipulihkan: percobaan ulang yang berhasil menghasilkan grant baru.
`subscription_paused`	Langganan dijeda (`subscription.paused`). Dapat dipulihkan: melanjutkan kembali menghasilkan grant baru.
`subscription_expired`	Langganan telah mencapai akhir masa berlakunya (`subscription.expired`).
`plan_changed`	Paket berubah; grant lama dicabut sebelum grant baru diterbitkan (`subscription.plan_changed`).
`refund`	Pengembalian dana telah diproses untuk pembayaran satu kali yang asli (`refund.succeeded`).
`manual`	Merchant mencabut grant melalui API atau dashboard. Pencabutan manual tidak secara otomatis diberikan kembali saat langganan diperpanjang.
`license_key_disabled`	Kunci lisensi di balik grant berbasis kunci lisensi dinonaktifkan. Grant akan diaktifkan kembali secara otomatis jika kunci diaktifkan kembali.
`platform_external`	Sisi platform dari suatu integrasi tidak lagi sinkron (misalnya, peran Discord dihapus secara manual, GitHub App kehilangan akses repositori, atau proses rekonsiliasi mendeteksi target yang hilang). Grant tidak akan diberikan kembali secara otomatis saat langganan diperpanjang hingga masalah platform yang mendasarinya terselesaikan.

Variasi Payload

Field data selalu merupakan objek EntitlementGrantResponse. Dua jenis integrasi menempelkan objek bersarang tambahan: Field data selalu berupa objek EntitlementGrantResponse. Payload membawa field integration_type (misalnya license_key, digital_files, discord) sehingga Anda dapat langsung mengenali jenis grant. Tiga jenis integrasi juga menyertakan objek bertingkat tambahan:

license_key disertakan ketika integration_type adalah license_key dan key telah diterbitkan. Objek ini berisi key yang dibuat, masa berlaku, dan penggunaan aktivasi. Untuk grant yang dipenuhi secara manual dan masih dalam status Pending, objek ini bernilai null hingga Anda memenuhi grant tersebut.
digital_product_delivery disertakan ketika integration_type adalah digital_files. Objek ini berisi URL unduhan yang telah ditandatangani sebelumnya, instructions opsional, dan external_url opsional.
feature disertakan ketika integration_type adalah feature_flag. Objek ini berisi feature_type dan feature_id dari kapabilitas yang diberikan oleh grant.

Untuk semua jenis integrasi lainnya (Discord, GitHub, Telegram, Figma, Framer, Notion), field bertingkat ini bernilai null; konfigurasi terkait tercatat dalam entitlement itu sendiri, bukan dalam grant.

Contoh Payload

Kunci lisensi dikirim (`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`)

Dipicu ketika customer membeli produk yang entitlement License Key-nya menggunakan fulfillment_mode: manual. Grant berstatus Pending tanpa objek license_key — merchant harus menyediakan 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"
  }
}

Tips Integrasi

Buka fitur yang bergantung saat grant mencapai Delivered. Event payment.succeeded memberi tahu Anda bahwa pembayaran telah berhasil, tetapi tidak memberi tahu bahwa pelanggan sudah memiliki repositori GitHub atau peran Discord. Tangani entitlement_grant.delivered, dan juga entitlement_grant.created dengan status: "Delivered", karena grant yang dikirim saat dibuat tidak memicu event delivered.
Petakan revocation_reason ke alur retensi. Pencabutan subscription_on_hold biasanya berarti kartu pelanggan gagal diproses dan perpanjangan berikutnya akan memberikan grant akses kembali. Pencabutan manual atau subscription_cancelled dilakukan secara sengaja. Perlakukan keduanya secara berbeda dalam pesan kepada pelanggan.
Deteksi duplikat menggunakan header webhook-id, bukan id milik grant. Grant memancarkan created satu kali, tetapi delivered dan revoked masing-masing dapat dipicu lebih dari sekali, karena grant yang dicabut dapat dipulihkan lalu dicabut kembali. failed juga tidak selalu final: grant OAuth yang gagal tetap dapat dikirimkan. Pengiriman ulang dari sistem webhook juga dapat mengulangi sebuah event. Lewati pengulangan berdasarkan webhook-id, dan gunakan id milik grant sebagai kunci untuk record grant Anda sendiri.
Baca integration_type untuk mengenali jenis grant. Payload memuat integration_type secara langsung (misalnya license_key, digital_files, discord). Objek bertingkat license_key dan digital_product_delivery akan terisi setelah grant masing-masing dikirimkan; grant kunci lisensi yang dipenuhi secara manual tetap Pending dengan integration_type: "license_key" dan null license_key hingga Anda memenuhinya.
Untuk grant berbasis OAuth, tampilkan oauth_url kepada pelanggan. Event entitlement_grant.created untuk alur pelanggan Discord, GitHub, atau Notion dapat menyertakan oauth_url dan oauth_expires_at. Jika null, tunggu event berikutnya atau arahkan pelanggan ke Customer Portal. Kirim URL tersebut melalui email kepada pelanggan atau tampilkan di aplikasi Anda untuk membuka blokir pengiriman.

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

brand_id

string

wajib

Brand id this grant belongs to.

business_id

string

wajib

Identifier of the business that owns the grant.

created_at

string<date-time>

wajib

Timestamp when the grant was created.

customer_id

string

wajib

Identifier of the customer the grant was issued to.

entitlement_id

string

wajib

Identifier of the entitlement this grant was issued from.

string

wajib

Unique identifier of the grant.

integration_type

enum<string>

wajib

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

Opsi yang tersedia:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

wajib

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

wajib

Lifecycle status of the grant.

Opsi yang tersedia:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

wajib

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 Webhook Events

Pemicu Event

entitlement_grant.created

entitlement_grant.revoked

Variasi Payload

Contoh Payload

Kunci lisensi dikirim (`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`)

Tips Integrasi

​Entitlement Grant Webhook Events

​Pemicu Event

​entitlement_grant.created

​entitlement_grant.revoked

​Variasi Payload

​Contoh Payload

​Kunci lisensi dikirim (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)

​Tips Integrasi

Entitlement Grant Webhook Events

Pemicu Event

entitlement_grant.created

entitlement_grant.revoked

Variasi Payload

Contoh Payload

Kunci lisensi dikirim (`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`)

Tips Integrasi