Skip to main content

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. Tutti e quattro gli eventi condividono lo stesso payload EntitlementGrantResponse documentato nello schema qui sotto.

Trigger degli Eventi

entitlement_grant.created

È stata appena inserita una riga di concessione. La concessione ha sempre un id 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_url che il cliente deve visitare per completare il consenso. Il grant rimane Pending finché il cliente non autorizza.
  • Integrazioni dirette con la piattaforma (Telegram, Framer, Digital Files) rimangono brevemente in Pending mentre viene eseguita la chiamata alla piattaforma, quindi passano a Delivered.
La concessione è passata da 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).
Tratta il codice entitlement_grant.failed come azionabile. Il cliente ha pagato ma non ha ottenuto l’accesso. Metti in evidenza i fallimenti al tuo team di supporto o attiva una nuova concessione una volta risolto il problema di base.

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 campo revocation_reason registra il trigger.

Varianti di Payload

Il campo data è 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 quando integration_type è license_key e una key è stata emessa. Contiene la key generata, la scadenza e l’utilizzo per l’attivazione. Per un grant soddisfatto manualmente ancora in stato Pending, questo oggetto è null finché non completi il fulfillment del grant.
  • digital_product_delivery è incluso quando integration_type è digital_files. Contiene URL di download presigned, l’elemento opzionale instructions e l’elemento opzionale external_url.
  • feature è incluso quando integration_type è feature_flag. Contiene feature_type e feature_id della capacità conferita dal grant.
Per tutti gli altri tipi di integrazione (Discord, GitHub, Telegram, Figma, Framer, Notion), questi campi annidati sono null; la configurazione pertinente è acquisita nell’entitlement stesso, non nel grant.

Esempi di Payload

Chiave di licenza consegnata (entitlement_grant.delivered)

Generato quando un cliente acquista un prodotto il cui entitlement License Key utilizza 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.delivered prima di sbloccare funzionalità dipendenti. Un evento payment.succeeded ti dice che il pagamento è stato completato; non ti dice ancora se il cliente ha il repository GitHub o il ruolo Discord. L’evento delivered è la fonte di verità per l’adempimento.
  • Mappa revocation_reason ai flussi di retention. Una revoca subscription_on_hold di solito significa che la carta del cliente ha fallito e il prossimo rinnovo concederà nuovamente l’accesso. Una revoca manual o subscription_cancelled è intenzionale. Trattali in modo diverso nella messaggistica al cliente.
  • Usa il grant id come tua chiave di idempotenza. Una singola concessione emette al massimo un evento created e al massimo un evento terminale (delivered o failed), e al massimo un evento revoked. Le riedizioni dal sistema webhook possono ripetere eventi; deduplicali sulla concessione id più type.
  • Esamina license_key e digital_product_delivery per 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_url al cliente. L’evento entitlement_grant.created per i flussi di abbonati a Discord, GitHub, o Notion include un oauth_url e oauth_expires_at. Invia un’email al cliente o mostrala nella tua app per sbloccare la consegna.

Suggerimenti per l’integrazione

  • Attendi entitlement_grant.delivered prima di sbloccare le funzionalità dipendenti. Un evento payment.succeeded indica che il pagamento è stato acquisito; non indica che il cliente disponga già del repository GitHub o del ruolo Discord. L’evento delivered è la fonte autorevole per il fulfillment.
  • Associa revocation_reason ai flussi di retention. Una revoca subscription_on_hold di solito significa che la carta del cliente non è andata a buon fine e che il rinnovo successivo concederà nuovamente l’accesso. Una revoca manual o subscription_cancelled è intenzionale. Gestiscile in modo diverso nei messaggi destinati ai clienti.
  • Usa id del grant come chiave di idempotenza. Un singolo grant genera al massimo un evento created, al massimo un evento terminale (delivered o failed) e al massimo un evento revoked. Le riconsegne del sistema webhook possono ripetere gli eventi; rimuovi i duplicati usando id del grant insieme a type.
  • Leggi integration_type per riconoscere il tipo di grant. Il payload contiene direttamente integration_type (ad esempio license_key, digital_files, discord). Gli oggetti annidati license_key e digital_product_delivery vengono valorizzati quando i rispettivi grant sono stati consegnati; un grant con license key soddisfatto manualmente rimane Pending con integration_type: "license_key" e un null license_key finché non completi il fulfillment.
  • Per i grant basati su OAuth, mostra oauth_url al cliente. L’evento entitlement_grant.created per i flussi degli iscritti a Discord, GitHub o Notion include oauth_url e oauth_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
string
obbligatorio

Brand id this grant belongs to.

business_id
string
obbligatorio

Identifier of the business that owns the grant.

created_at
string<date-time>
obbligatorio

Timestamp when the grant was created.

customer_id
string
obbligatorio

Identifier of the customer the grant was issued to.

entitlement_id
string
obbligatorio

Identifier of the entitlement this grant was issued from.

id
string
obbligatorio

Unique identifier of the grant.

integration_type
enum<string>
obbligatorio

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

Opzioni disponibili:
discord,
telegram,
github,
figma,
framer,
notion,
digital_files,
license_key,
feature_flag
metadata
Metadata · object
obbligatorio

Arbitrary key-value metadata recorded on the grant.

status
enum<string>
obbligatorio

Lifecycle status of the grant.

Opzioni disponibili:
Pending,
Delivered,
Failed,
Revoked
updated_at
string<date-time>
obbligatorio

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.

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.

license_key
null | object

License-key delivery payload, present when the entitlement integration is license_key.

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.

Ultima modifica il 21 agosto 2026