Concessione di Diritti

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.

Evento	Descrizione
`entitlement_grant.created`	È stata creata una nuova riga grant. Lo stato è `Delivered` immediatamente per le license key e i feature flag evasi automaticamente, e `Pending` per le license key evase manualmente e per ogni altra integrazione.
`entitlement_grant.delivered`	Il grant passa allo stato delivered. Il cliente ora ha accesso alla piattaforma, al file o alla license key inclusi nel diritto.
`entitlement_grant.failed`	La delivery non è riuscita e non verrà ritentata. Esamina `error_code` e `error_message`.
`entitlement_grant.revoked`	L’accesso è stato revocato. Esamina `revocation_reason` per capire il motivo.

Tutti e quattro gli eventi condividono lo stesso payload EntitlementGrantResponse documentato nello schema qui sotto.

Trigger degli Eventi

entitlement_grant.created

È stata inserita una riga grant. Da questo momento il grant ha sempre un id stabile, anche se il suo stato cambia. Usa questo evento per registrare che l’evasione è in corso. Per le license key evase automaticamente e i feature flag, la riga viene inserita direttamente con status: "Delivered" e delivered_at valorizzati, quindi un singolo evento created non è seguito da ulteriori cambiamenti di stato, a meno che il grant non venga revocato successivamente. 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:

Le integrazioni basate su OAuth (Discord, GitHub, Notion) utilizzano un oauth_url che il cliente deve visitare per completare il consenso. Dodo Payments prova a crearlo quando viene creato il grant, quindi entitlement_grant.created potrebbe includerlo; se è null, viene compilato quando il cliente avvia il flusso di accettazione dal Customer Portal. Il grant rimane Pending finché il cliente non lo autorizza.
Le integrazioni dirette con la piattaforma (Telegram, Framer, Digital Files) rimangono in Pending solo brevemente 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 a Delivered, generalmente da Pending. Il cliente ora dispone dell’accesso descritto dal diritto. Usa questo evento per sbloccare le funzionalità dipendenti nei tuoi sistemi, ad esempio per effettuare il provisioning di un workspace, inviare un’email di benvenuto personalizzata o contrassegnare un flag “fulfilled”. Il campo delivered_at del payload registra il momento in cui la delivery è stata completata. delivered viene emesso ogni volta che lo stato di un grant esistente cambia in Delivered: da Pending, quando un grant OAuth fallito ha successivamente esito positivo, o quando un grant revocato viene ripristinato. Un grant che arriva a Delivered al momento della creazione, come una license key evasa automaticamente, emette solo created. 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.

`revocation_reason`	Trigger
`subscription_cancelled`	L’abbonamento del cliente è stato cancellato (evento `subscription.cancelled`).
`subscription_on_hold`	L’abbonamento è in sospeso a causa di un rinnovo fallito (event `subscription.on_hold`). Recuperabile: un ritentativo riuscito produce una nuova concessione.
`subscription_expired`	L’abbonamento ha raggiunto la fine del suo termine (evento `subscription.expired`).
`plan_changed`	Il piano è cambiato; le vecchie concessioni sono revocate prima che ne vengano emesse di nuove (evento `subscription.plan_changed`).
`refund`	Un rimborso è stato elaborato per il pagamento originale unico (evento `refund.succeeded`).
`manual`	Un commerciante ha revocato la concessione tramite l’API o la dashboard. Le revoche manuali non vengono automaticamente concesse nuovamente al rinnovo dell’abbonamento.
`license_key_disabled`	La chiave di licenza dietro una concessione di chiavi di licenza è stata disabilitata. La concessione è riattivata automaticamente se la chiave è riabilitata.
`platform_external`	Il lato della piattaforma di un’integrazione è uscito dalla sincronizzazione (per esempio, un ruolo Discord è stato rimosso manualmente, l’app GitHub ha perso l’accesso al repository, o un passaggio di riconciliazione ha rilevato un target mancante). La concessione non viene automaticamente ripristinata al rinnovo dell’abbonamento fino a quando il problema di base della piattaforma non viene risolto.

`revocation_reason`	Trigger
`subscription_cancelled`	L’abbonamento del cliente è stato annullato (evento `subscription.cancelled`).
`subscription_on_hold`	L’abbonamento è sospeso a causa di un rinnovo non riuscito (`subscription.on_hold`). Recuperabile: un nuovo tentativo riuscito genera una nuova concessione.
`subscription_paused`	L’abbonamento è stato messo in pausa (`subscription.paused`). Recuperabile: la ripresa genera una nuova concessione.
`subscription_expired`	L’abbonamento ha raggiunto la fine del periodo (`subscription.expired`).
`plan_changed`	Il piano è cambiato; le concessioni precedenti vengono revocate prima dell’emissione di quelle nuove (`subscription.plan_changed`).
`refund`	È stato elaborato un rimborso per il pagamento una tantum originale (`refund.succeeded`).
`manual`	Un merchant ha revocato la concessione tramite l’API o la dashboard. Le revoche manuali non vengono concesse nuovamente automaticamente al rinnovo dell’abbonamento.
`license_key_disabled`	La license key alla base di una concessione basata su license key è stata disabilitata. La concessione viene riattivata automaticamente se la chiave viene nuovamente abilitata.
`platform_external`	Il lato platform di un’integrazione non è più sincronizzato (ad esempio, un ruolo Discord è stato rimosso manualmente, la GitHub App ha perso l’accesso al repository oppure un passaggio di riconciliazione ha rilevato una destinazione mancante). La concessione non viene nuovamente assegnata automaticamente al rinnovo dell’abbonamento finché il problema della platform sottostante non viene risolto.

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`)

License Key consegnata (`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 in attesa di evasione manuale (`entitlement_grant.created`)

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.

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

File digitali consegnati (`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"
  }
}

Ruolo Discord creato e in attesa (`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 revocato in seguito alla cancellazione dell’abbonamento (`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 non riuscita (`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"
  }
}

Suggerimenti per l’integrazione

Sblocca le funzionalità dipendenti quando un grant raggiunge Delivered. Un evento payment.succeeded ti informa che il pagamento è stato completato; non indica che il cliente abbia già il repository GitHub o il ruolo Discord. Gestisci entitlement_grant.delivered e anche entitlement_grant.created con status: "Delivered", perché un grant consegnato al momento della creazione non genera alcun evento delivered.
Associa revocation_reason ai flussi di retention. Una revoca subscription_on_hold di solito indica 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 al cliente.
Rileva i duplicati con l’header webhook-id, non con id del grant. Un grant emette created una sola volta, ma delivered e revoked possono essere attivati più volte, perché un grant revocato può essere ripristinato e revocato nuovamente. Anche failed non è sempre definitivo: un grant OAuth non riuscito può comunque essere consegnato. Le nuove consegne dal sistema webhook possono inoltre ripetere un evento. Ignora le ripetizioni usando webhook-id e usa id del grant come chiave per i tuoi record dei grant.
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 popolati dopo la consegna dei rispettivi grant; un grant con license key completato manualmente rimane Pending con integration_type: "license_key" e un null license_key finché non lo completi.
Per i grant basati su OAuth, mostra oauth_url al cliente. L’evento entitlement_grant.created per i flussi degli abbonati Discord, GitHub o Notion può includere un oauth_url e oauth_expires_at. Se è null, attendi un evento successivo o indirizza il cliente al Customer Portal. Invia l’URL al cliente tramite email oppure visualizzalo nella tua app per sbloccare la consegna.

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.

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.

Show child attributes

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.

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

Eventi Webhook di Concessione di Diritti

Trigger degli Eventi

entitlement_grant.created

entitlement_grant.revoked

Varianti di Payload

Esempi di Payload

Chiave di licenza consegnata (`entitlement_grant.delivered`)

License Key consegnata (`entitlement_grant.delivered`)

License Key in attesa di evasione manuale (`entitlement_grant.created`)

File digitali consegnati (`entitlement_grant.delivered`)

Ruolo Discord creato e in attesa (`entitlement_grant.created`)

Grant revocato in seguito alla cancellazione dell’abbonamento (`entitlement_grant.revoked`)

Delivery non riuscita (`entitlement_grant.failed`)

Suggerimenti per l’integrazione

​Eventi Webhook di Concessione di Diritti

​Trigger degli Eventi

​entitlement_grant.created

​entitlement_grant.revoked

​Varianti di Payload

​Esempi di Payload

​Chiave di licenza consegnata (entitlement_grant.delivered)

​License Key consegnata (entitlement_grant.delivered)

​License Key in attesa di evasione manuale (entitlement_grant.created)

​File digitali consegnati (entitlement_grant.delivered)

​Ruolo Discord creato e in attesa (entitlement_grant.created)

​Grant revocato in seguito alla cancellazione dell’abbonamento (entitlement_grant.revoked)

​Delivery non riuscita (entitlement_grant.failed)

​Suggerimenti per l’integrazione

Eventi Webhook di Concessione di Diritti

Trigger degli Eventi

entitlement_grant.created

entitlement_grant.revoked

Varianti di Payload

Esempi di Payload

Chiave di licenza consegnata (`entitlement_grant.delivered`)

License Key consegnata (`entitlement_grant.delivered`)

License Key in attesa di evasione manuale (`entitlement_grant.created`)

File digitali consegnati (`entitlement_grant.delivered`)

Ruolo Discord creato e in attesa (`entitlement_grant.created`)

Grant revocato in seguito alla cancellazione dell’abbonamento (`entitlement_grant.revoked`)

Delivery non riuscita (`entitlement_grant.failed`)

Suggerimenti per l’integrazione