Concessione di Diritti
Il payload inviato al tuo endpoint webhook quando una concessione di diritti è creata, consegnata, fallita o revocata.
Eventi Webhook di Concessione di Diritti
Questi eventi vengono attivati ogni volta che lo stato della concessione di diritti di un cliente cambia, ad esempio quando viene generata una chiave di licenza, viene assegnato un ruolo Discord, viene fornito un link di download, o l’accesso viene revocato. Abbonati a questi eventi per mantenere la tua applicazione sincronizzata con ciò a cui ogni cliente può accedere.EntitlementGrantResponse documentato nello schema qui sotto.
Trigger degli Eventi
entitlement_grant.created
È stata appena inserita una riga di concessione. La concessione ha sempre unid stabile da questo momento in poi, anche se il suo stato cambia. Usa questo evento per registrare che l’adempimento è in corso.
Per le license key soddisfatte automaticamente, la riga viene inserita direttamente con status: "Delivered" e delivered_at valorizzati, quindi a un singolo evento created non seguono ulteriori cambiamenti di stato, a meno che il grant non venga revocato in seguito.
Per le license key soddisfatte manualmente (entitlement con fulfillment_mode: manual), la riga arriva con status: "Pending" e senza l’oggetto license_key: la key non è ancora disponibile. Questo evento segnala che una key è in attesa di fulfillment; fornisci la key tramite POST /grants/{grant_id}/license-key, che genera quindi entitlement_grant.delivered. Consulta Manual Fulfillment.
Per ogni altra integrazione, la riga arriva con status: "Pending". Al completamento della delivery segue un evento delivered o failed:
- Integrazioni basate su OAuth (Discord, GitHub, Notion) includono un
oauth_urlche il cliente deve visitare per completare il consenso. Il grant rimanePendingfinché il cliente non autorizza. - Integrazioni dirette con la piattaforma (Telegram, Framer, Digital Files) rimangono brevemente in
Pendingmentre viene eseguita la chiamata alla piattaforma, quindi passano aDelivered.
pending a delivered. Il cliente ora ha l’accesso descritto dal diritto. Usa questo evento per sbloccare funzionalità dipendenti nei tuoi sistemi, per esempio per fornire uno spazio di lavoro, inviare un’email di benvenuto personalizzata, o segnare un flag “adempiuto”.
Il grant è passato da Pending a Delivered. Il cliente ora dispone dell’accesso descritto dall’entitlement. Usa questo evento per sbloccare le funzionalità dipendenti nei tuoi sistemi, ad esempio per eseguire il provisioning di un workspace, inviare un’email di benvenuto personalizzata o contrassegnare un flag come “fulfilled”.
Il campo delivered_at del payload indica quando è stata completata la delivery. Per i grant che arrivano in stato Delivered al momento della creazione, riceverai gli eventi created e delivered consecutivamente.
La consegna è stata tentata e fallita con un errore non ripetibile. I campi error_code e error_message spiegano il fallimento. Cause comuni includono un token OAuth revocato, un permesso della piattaforma negato, o un target mancante (es. una gilda Discord eliminata).
entitlement_grant.revoked
L’accesso è stato revocato a livello di piattaforma: ruolo Discord rimosso, collaboratore GitHub rimosso, chiave di licenza disabilitata, URL di download del file non più emessi. Il camporevocation_reason registra il trigger.
Varianti di Payload
Il campodata è sempre un oggetto EntitlementGrantResponse. Due tipi di integrazione allegano oggetti annidati extra:
Il campo data è sempre un oggetto EntitlementGrantResponse. Il payload contiene un campo integration_type (ad esempio license_key, digital_files, discord) che consente di riconoscere direttamente il tipo di grant. Tre tipi di integrazione includono inoltre oggetti annidati aggiuntivi:
license_keyè incluso quandointegration_typeèlicense_keye una key è stata emessa. Contiene la key generata, la scadenza e l’utilizzo per l’attivazione. Per un grant soddisfatto manualmente ancora in statoPending, questo oggetto ènullfinché non completi il fulfillment del grant.digital_product_deliveryè incluso quandointegration_typeèdigital_files. Contiene URL di download presigned, l’elemento opzionaleinstructionse l’elemento opzionaleexternal_url.featureè incluso quandointegration_typeèfeature_flag. Contienefeature_typeefeature_iddella capacità conferita dal grant.
null; la configurazione pertinente è acquisita nell’entitlement stesso, non nel grant.
Esempi di Payload
Chiave di licenza consegnata (entitlement_grant.delivered)
fulfillment_mode: manual. Il grant è Pending e non contiene ancora l’oggetto license_key: il merchant deve fornire la key.
Concessione revocata al momento della cancellazione dell’abbonamento (entitlement_grant.revoked)
Consegna fallita (entitlement_grant.failed)
- Aspetta
entitlement_grant.deliveredprima di sbloccare funzionalità dipendenti. Un eventopayment.succeededti dice che il pagamento è stato completato; non ti dice ancora se il cliente ha il repository GitHub o il ruolo Discord. L’eventodeliveredè la fonte di verità per l’adempimento. - Mappa
revocation_reasonai flussi di retention. Una revocasubscription_on_holddi solito significa che la carta del cliente ha fallito e il prossimo rinnovo concederà nuovamente l’accesso. Una revocamanualosubscription_cancelledè intenzionale. Trattali in modo diverso nella messaggistica al cliente. - Usa il grant
idcome tua chiave di idempotenza. Una singola concessione emette al massimo un eventocreatede al massimo un evento terminale (deliveredofailed), e al massimo un eventorevoked. Le riedizioni dal sistema webhook possono ripetere eventi; deduplicali sulla concessioneidpiùtype. - Esamina
license_keyedigital_product_deliveryper riconoscere il tipo di integrazione. Il payload della concessione stessa non trasporta il tipo di integrazione, ma esattamente uno di questi oggetti annidati è popolato per le concessioni di chiavi di licenza e file digitali. - Per concessioni basate su OAuth, metti in evidenza
oauth_urlal cliente. L’eventoentitlement_grant.createdper i flussi di abbonati a Discord, GitHub, o Notion include unoauth_urleoauth_expires_at. Invia un’email al cliente o mostrala nella tua app per sbloccare la consegna.
Suggerimenti per l’integrazione
- Attendi
entitlement_grant.deliveredprima di sbloccare le funzionalità dipendenti. Un eventopayment.succeededindica che il pagamento è stato acquisito; non indica che il cliente disponga già del repository GitHub o del ruolo Discord. L’eventodeliveredè la fonte autorevole per il fulfillment. - Associa
revocation_reasonai flussi di retention. Una revocasubscription_on_holddi solito significa che la carta del cliente non è andata a buon fine e che il rinnovo successivo concederà nuovamente l’accesso. Una revocamanualosubscription_cancelledè intenzionale. Gestiscile in modo diverso nei messaggi destinati ai clienti. - Usa
iddel grant come chiave di idempotenza. Un singolo grant genera al massimo un eventocreated, al massimo un evento terminale (deliveredofailed) e al massimo un eventorevoked. Le riconsegne del sistema webhook possono ripetere gli eventi; rimuovi i duplicati usandoiddel grant insieme atype. - Leggi
integration_typeper riconoscere il tipo di grant. Il payload contiene direttamenteintegration_type(ad esempiolicense_key,digital_files,discord). Gli oggetti annidatilicense_keyedigital_product_deliveryvengono valorizzati quando i rispettivi grant sono stati consegnati; un grant con license key soddisfatto manualmente rimanePendingconintegration_type: "license_key"e unnulllicense_keyfinché non completi il fulfillment. - Per i grant basati su OAuth, mostra
oauth_urlal cliente. L’eventoentitlement_grant.createdper i flussi degli iscritti a Discord, GitHub o Notion includeoauth_urleoauth_expires_at. Invialo al cliente tramite email o visualizzalo nella tua app per sbloccare la delivery.
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.