Entitlement Grant
Payload yang dikirim ke endpoint webhook Anda ketika pemberian hak istimewa dibuat, dikirim, gagal, atau dibatalkan.
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.EntitlementGrantResponse yang sama seperti yang didokumentasikan dalam skema di bawah.
Pemicu Event
entitlement_grant.created
Baris pemberian baru saja dimasukkan. Pemberian selalu memilikiid yang stabil sejak saat ini, bahkan jika statusnya berubah. Gunakan event ini untuk mencatat bahwa pemenuhan sedang berlangsung.
Untuk license key yang dipenuhi secara otomatis, baris langsung disisipkan dengan status: "Delivered" dan delivered_at yang telah terisi, sehingga satu event created tidak diikuti perubahan status lebih lanjut, kecuali grant tersebut kemudian 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) menyertakan
oauth_urlyang harus dikunjungi customer untuk menyelesaikan persetujuan. Grant tetap dalam statusPendinghingga customer memberikan otorisasi. - Integrasi langsung ke platform (Telegram, Framer, Digital Files) hanya berada dalam status
Pendingsebentar saat panggilan ke platform berlangsung, lalu beralih keDelivered.
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 dari Pending ke Delivered. Customer kini memiliki akses yang dijelaskan oleh entitlement. Gunakan event ini untuk membuka fitur dependen di sistem Anda sendiri, misalnya menyediakan workspace, mengirim email sambutan khusus, atau menandai flag “fulfilled”.
Field delivered_at pada payload mencatat kapan pengiriman selesai. Untuk grant yang sejak awal dibuat dengan status Delivered, Anda akan menerima event created dan delivered secara berurutan.
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).
entitlement_grant.revoked
Akses ditarik di tingkat platform: peran Discord dihapus, kolaborator GitHub dihapus, kunci lisensi dinonaktifkan, URL unduhan file tidak lagi diterbitkan. Fieldrevocation_reason mencatat pemicu.
Variasi Payload
Fielddata 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_keydisertakan ketikaintegration_typeadalahlicense_keydan key telah diterbitkan. Objek ini berisi key yang dibuat, masa berlaku, dan penggunaan aktivasi. Untuk grant yang dipenuhi secara manual dan masih dalam statusPending, objek ini bernilainullhingga Anda memenuhi grant tersebut.digital_product_deliverydisertakan ketikaintegration_typeadalahdigital_files. Objek ini berisi URL unduhan yang telah ditandatangani sebelumnya,instructionsopsional, danexternal_urlopsional.featuredisertakan ketikaintegration_typeadalahfeature_flag. Objek ini berisifeature_typedanfeature_iddari kapabilitas yang diberikan oleh grant.
null; konfigurasi terkait tercatat dalam entitlement itu sendiri, bukan dalam grant.
Contoh Payload
Kunci lisensi dikirim (entitlement_grant.delivered)
fulfillment_mode: manual. Grant berstatus Pending tanpa objek license_key — merchant harus menyediakan key.
Pemberian dicabut pada pembatalan langganan (entitlement_grant.revoked)
Pengiriman gagal (entitlement_grant.failed)
- Tunggu
entitlement_grant.deliveredsebelum membuka fitur yang bergantung. Sebuah eventpayment.succeededmemberi tahu Anda bahwa pembayaran telah diterima; itu tidak memberi tahu Anda bahwa pelanggan memiliki repo GitHub atau peran Discord. Eventdeliveredadalah sumber kebenaran untuk pemenuhan. - Petakan
revocation_reasonke alur retensi. Pencabutansubscription_on_holdbiasanya berarti kartu pelanggan gagal dan pembaruan berikutnya akan memberikan kembali akses. Pencabutanmanualatausubscription_cancelledadalah disengaja. Perlakukan mereka secara berbeda dalam komunikasi pelanggan. - Gunakan
idpemberian sebagai kunci idempoten Anda. Sebuah pemberian tunggal mengeluarkan paling banyak satu eventcreateddan paling banyak satu event terminal (deliveredataufailed), dan paling banyak satu eventrevoked. Pengiriman ulang dari sistem webhook dapat mengulangi acara; hapus duplikasi padaidpemberian plustype. - Periksa
license_keydandigital_product_deliveryuntuk mengenali jenis integrasi. Payload pemberian itu sendiri tidak membawa jenis integrasi, tetapi tepat satu dari objek bersarang ini terisi untuk pemberian kunci-lisensi dan file digital. - Untuk pemberian berbasis OAuth, tampilkan
oauth_urlkepada pelanggan. Evententitlement_grant.createduntuk alur pelanggan Discord, GitHub, atau Notion menyertakanoauth_urldanoauth_expires_at. Kirim email kepada pelanggan atau tampilkan dalam aplikasi Anda untuk membuka blokir pengiriman.
Tips Integrasi
- Tunggu
entitlement_grant.deliveredsebelum membuka fitur dependen. Eventpayment.succeededmenandakan bahwa pembayaran telah berhasil, bukan bahwa customer sudah memiliki repo GitHub atau role Discord. Eventdeliveredadalah sumber kebenaran untuk pemenuhan. - Petakan
revocation_reasonke alur retensi. Pencabutansubscription_on_holdbiasanya berarti kartu customer gagal dan perpanjangan berikutnya akan memberikan kembali akses. Pencabutanmanualatausubscription_cancelleddilakukan secara sengaja. Perlakukan keduanya secara berbeda dalam komunikasi kepada customer. - Gunakan
idgrant sebagai kunci idempotensi Anda. Satu grant memicu paling banyak satu eventcreateddan paling banyak satu event terminal (deliveredataufailed), serta paling banyak satu eventrevoked. Pengiriman ulang dari sistem webhook dapat mengulangi event; lakukan deduplikasi berdasarkanidgrant dantype. - Baca
integration_typeuntuk mengenali jenis grant. Payload membawaintegration_typesecara langsung (misalnyalicense_key,digital_files,discord). Objek bertingkatlicense_keydandigital_product_deliveryterisi setelah grant terkait terpenuhi; grant license key yang dipenuhi secara manual tetap dalam statusPendingdenganintegration_type: "license_key"dannulllicense_keyhingga Anda memenuhinya. - Untuk grant berbasis OAuth, tampilkan
oauth_urlkepada customer. Evententitlement_grant.createduntuk alur subscriber Discord, GitHub, atau Notion menyertakanoauth_urldanoauth_expires_at. Kirimkan melalui email kepada customer atau tampilkan di aplikasi Anda untuk melanjutkan pengiriman.
Detailed view of a single entitlement grant: who it's for, its lifecycle state, and any integration-specific delivery payload.
Brand id this grant belongs to.
Identifier of the business that owns the grant.
Timestamp when the grant was created.
Identifier of the customer the grant was issued to.
Identifier of the entitlement this grant was issued from.
Unique identifier of the grant.
The integration type of the grant's entitlement (e.g. license_key).
discord, telegram, github, figma, framer, notion, digital_files, license_key, feature_flag Arbitrary key-value metadata recorded on the grant.
Lifecycle status of the grant.
Pending, Delivered, Failed, Revoked Timestamp when the grant was last modified.
Timestamp when the grant transitioned to delivered, when applicable.
Digital-product-delivery payload, present when the entitlement
integration is digital_files.
Machine-readable code reported when delivery failed, when applicable.
Human-readable message reported when delivery failed, when applicable.
Typed feature payload, present only when the entitlement integration is
feature_flag; null for every other integration type.
License-key delivery payload, present when the entitlement integration
is license_key.
Timestamp when oauth_url stops being valid, when applicable.
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.
Identifier of the payment that triggered this grant, when applicable.
Reason recorded when the grant was revoked, when applicable.
Timestamp when the grant transitioned to revoked, when applicable.
Identifier of the subscription that triggered this grant, when applicable.