Entitlement-Gewährung

Entitlement-Gewährung Webhook-Ereignisse

Diese Ereignisse werden ausgelöst, wann immer sich der Status einer Entitlement-Gewährung eines Kunden ändert, zum Beispiel wenn ein Lizenzschlüssel generiert wird, eine Discord-Rolle zugewiesen wird, ein Download-Link bereitgestellt wird oder der Zugriff widerrufen wird. Abonnieren Sie diese Ereignisse, um Ihre Anwendung mit dem zu synchronisieren, worauf jeder Kunde zugreifen kann.

Event	Beschreibung
`entitlement_grant.created`	Eine neue Grant-Zeile wurde erstellt. Der Status ist bei automatisch erfüllten License Keys und Feature Flags sofort `Delivered` und bei manuell erfüllten License Keys und allen anderen Integrationen `Pending`.
`entitlement_grant.delivered`	Der Grant wechselt zu „delivered“. Der Kunde hat nun Zugriff auf die berechtigte Plattform, Datei oder den License Key.
`entitlement_grant.failed`	Die Zustellung ist fehlgeschlagen und wird nicht erneut versucht. Prüfe `error_code` und `error_message`.
`entitlement_grant.revoked`	Der Zugriff wurde entzogen. Prüfe `revocation_reason`, um den Grund zu verstehen.

Alle vier Ereignisse teilen sich die gleiche EntitlementGrantResponse Nutzlast, die im untenstehenden Schema dokumentiert ist.

Ereignisauslöser

entitlement_grant.created

Eine Grant-Zeile wurde eingefügt. Der Grant verfügt ab diesem Zeitpunkt immer über eine stabile id, auch wenn sich sein Status ändert. Verwende dieses Event, um zu protokollieren, dass die Erfüllung läuft. Bei automatisch erfüllten License Keys und Feature Flags wird die Zeile direkt mit ausgefüllten Werten für status: "Delivered" und delivered_at eingefügt. Daher folgen auf ein einzelnes created Event keine weiteren Statusänderungen, sofern der Grant nicht später widerrufen wird. Bei manuell erfüllten Lizenzschlüsseln (Entitlements mit fulfillment_mode: manual) wird die Zeile mit status: "Pending" und ohne Objekt license_key erstellt — es gibt noch keinen Schlüssel. Dieses Ereignis signalisiert, dass ein Schlüssel auf die Erfüllung wartet. Stelle ihn über POST /grants/{grant_id}/license-key bereit; dadurch wird anschließend entitlement_grant.delivered ausgelöst. Siehe Manual Fulfillment. Bei jeder anderen Integration wird die Zeile mit status: "Pending" erstellt. Sobald die Zustellung abgeschlossen ist, folgt ein Ereignis delivered oder failed:

OAuth-basierte Integrationen (Discord, GitHub, Notion) verwenden einen oauth_url, den der Kunde aufrufen muss, um die Einwilligung abzuschließen. Dodo Payments versucht, ihn bei der Erstellung des Grants zu erstellen, daher kann entitlement_grant.created ihn enthalten; wenn er null ist, wird er ausgefüllt, wenn der Kunde den Accept-Flow über das Customer Portal startet. Der Grant bleibt Pending, bis der Kunde ihn autorisiert.
Plattformdirekte Integrationen (Telegram, Framer, Digital Files) befinden sich nur kurz in Pending, während der Plattformaufruf ausgeführt wird, und wechseln anschließend zu Delivered.

Die Gewährung ist von pending zu delivered übergegangen. Der Kunde hat jetzt den Zugriff, der durch die Berechtigung beschrieben wird. Verwenden Sie dieses Ereignis, um abhängige Funktionen in Ihren eigenen Systemen freizuschalten, z. B. um einen Arbeitsbereich bereitzustellen, eine benutzerdefinierte Willkommens-E-Mail zu senden oder eine “erfüllt”-Flagge zu setzen. Der Grant ist zu Delivered übergegangen, üblicherweise von Pending. Der Kunde hat nun den durch die Berechtigung beschriebenen Zugriff. Verwende dieses Event, um abhängige Funktionen in deinen eigenen Systemen freizuschalten, beispielsweise um einen Workspace bereitzustellen, eine individuelle Willkommens-E-Mail zu senden oder ein „fulfilled“-Flag zu setzen. Das Feld delivered_at der Payload erfasst, wann die Zustellung abgeschlossen wurde. delivered wird immer ausgelöst, wenn sich der Status eines bestehenden Grants zu Delivered ändert: von Pending, wenn ein fehlgeschlagener OAuth-Grant später erfolgreich ist oder wenn ein widerrufener Grant wiederhergestellt wird. Ein Grant, der bei der Erstellung als Delivered eintrifft, etwa ein automatisch erfüllter License Key, löst nur created aus. Die Lieferung wurde versucht und ist mit einem nicht wiederholbaren Fehler fehlgeschlagen. Die Felder error_code und error_message erklären das Scheitern. Häufige Ursachen sind ein widerrufenes OAuth-Token, eine verweigerte Plattformberechtigung oder ein fehlendes Ziel (z. B. eine gelöschte Discord-Gilde).

Behandeln Sie entitlement_grant.failed als umsetzbar. Der Kunde hat bezahlt, aber keinen Zugriff erhalten. Leiten Sie Misserfolge an Ihr Support-Team weiter oder lösen Sie eine Neuerteilung aus, sobald das zugrunde liegende Problem gelöst ist.

entitlement_grant.revoked

Der Zugriff wurde auf Plattformebene widerrufen: Discord-Rolle entfernt, GitHub-Kollaborateur entfernt, Lizenzschlüssel deaktiviert, Download-URLs für Dateien werden nicht mehr ausgegeben. Das revocation_reason Feld zeichnet den Auslöser auf.

`revocation_reason`	Auslöser
`subscription_cancelled`	Das Abonnement des Kunden wurde storniert (`subscription.cancelled` Ereignis).
`subscription_on_hold`	Das Abonnement ist aufgrund eines fehlgeschlagenen Erneuerungsversuchs angehalten (`subscription.on_hold`). Wiederherstellbar: Ein erfolgreicher erneuter Versuch führt zu einer Neugewährung.
`subscription_expired`	Das Abonnement hat sein Ende der Laufzeit erreicht (`subscription.expired`).
`plan_changed`	Der Plan hat sich geändert; alte Gewährungen werden widerrufen, bevor neue ausgestellt werden (`subscription.plan_changed`).
`refund`	Eine Rückerstattung wurde für die ursprüngliche Einmalzahlung verarbeitet (`refund.succeeded`).
`manual`	Ein Händler hat die Gewährung über die API oder das Dashboard widerrufen. Manuelle Widerrufe werden bei Abonnementerneuerung nicht automatisch neu gewährt.
`license_key_disabled`	Der Lizenzschlüssel hinter einer Lizenzschlüssel-Gewährung wurde deaktiviert. Die Gewährung wird automatisch reaktiviert, wenn der Schlüssel wieder aktiviert wird.
`platform_external`	Die Plattform-Seite einer Integration ist aus der Synchronisation geraten (zum Beispiel wurde eine Discord-Rolle manuell entfernt, die GitHub-App hat den Repository-Zugriff verloren, oder ein Abgleichsprozess hat ein fehlendes Ziel erkannt). Die Gewährung wird bei Abonnementerneuerung nicht automatisch neu gewährt, bis das zugrunde liegende Plattformproblem gelöst ist.

`revocation_reason`	Auslöser
`subscription_cancelled`	Das Abonnement des Kunden wurde gekündigt (`subscription.cancelled`-Ereignis).
`subscription_on_hold`	Das Abonnement ist aufgrund einer fehlgeschlagenen Verlängerung pausiert (`subscription.on_hold`). Wiederherstellbar: Ein erfolgreicher Wiederholungsversuch führt zu einer erneuten Gewährung.
`subscription_paused`	Das Abonnement wurde pausiert (`subscription.paused`). Wiederherstellbar: Durch die Fortsetzung wird die Berechtigung erneut gewährt.
`subscription_expired`	Das Abonnement hat das Ende seiner Laufzeit erreicht (`subscription.expired`).
`plan_changed`	Der Plan wurde geändert; alte Berechtigungen werden widerrufen, bevor neue gewährt werden (`subscription.plan_changed`).
`refund`	Eine Rückerstattung wurde für die ursprüngliche einmalige Zahlung verarbeitet (`refund.succeeded`).
`manual`	Ein Händler hat die Berechtigung über die API oder das Dashboard widerrufen. Manuelle Widerrufe werden bei der Verlängerung des Abonnements nicht automatisch erneut gewährt.
`license_key_disabled`	Der Lizenzschlüssel hinter einer Lizenzschlüssel-Berechtigung wurde deaktiviert. Die Berechtigung wird automatisch wieder aktiviert, wenn der Schlüssel erneut aktiviert wird.
`platform_external`	Die Plattformseite einer Integration ist nicht mehr synchron (beispielsweise wurde eine Discord-Rolle manuell entfernt, die GitHub App hat den Zugriff auf das Repository verloren oder ein Abgleich hat ein fehlendes Ziel erkannt). Die Berechtigung wird bei der Verlängerung des Abonnements nicht automatisch erneut gewährt, solange das zugrunde liegende Plattformproblem nicht behoben ist.

Nutzlastvarianten

Das data Feld ist immer ein EntitlementGrantResponse Objekt. Zwei Integrationstypen hängen zusätzliche verschachtelte Objekte an: Das Feld data ist immer ein Objekt vom Typ EntitlementGrantResponse. Die Payload enthält ein Feld integration_type (zum Beispiel license_key, digital_files, discord), sodass du den Grant-Typ direkt erkennen kannst. Drei Integrationstypen enthalten außerdem zusätzliche verschachtelte Objekte:

license_key ist enthalten, wenn integration_type license_key entspricht und ein Schlüssel ausgestellt wurde. Es enthält den generierten Schlüssel, das Ablaufdatum und die Aktivierungsnutzung. Bei einem manuell erfüllten Grant, der noch Pending ist, lautet dieses Objekt null, bis du den Grant erfüllst.
digital_product_delivery ist enthalten, wenn integration_type digital_files entspricht. Es enthält vorab signierte Download-URLs, das optionale instructions und das optionale external_url.
feature ist enthalten, wenn integration_type feature_flag entspricht. Es enthält feature_type und feature_id der durch den Grant gewährten Funktionalität.

Bei allen anderen Integrationstypen (Discord, GitHub, Telegram, Figma, Framer, Notion) lauten diese verschachtelten Felder null. Die relevante Konfiguration ist im Entitlement selbst und nicht im Grant enthalten.

Beispiel-Nutzlasten

Lizenzschlüssel geliefert (`entitlement_grant.delivered`)

License Key zugestellt (`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 wartet auf manuelle Erfüllung (`entitlement_grant.created`)

Wird ausgelöst, wenn ein Kunde ein Produkt kauft, dessen License-Key-Entitlement fulfillment_mode: manual verwendet. Der Grant ist Pending und enthält noch kein Objekt license_key — der Merchant muss den Schlüssel bereitstellen.

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

Digitale Dateien zugestellt (`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-Rolle erstellt und ausstehend (`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 bei Kündigung des Abonnements widerrufen (`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"
  }
}

Zustellung fehlgeschlagen (`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"
  }
}

Integrationstipps

Schalte abhängige Funktionen frei, sobald ein Grant Delivered erreicht. Ein payment.succeeded-Ereignis teilt dir mit, dass die Zahlung eingegangen ist; es bedeutet nicht, dass der Kunde bereits über das GitHub-Repository oder die Discord-Rolle verfügt. Verarbeite entitlement_grant.delivered sowie entitlement_grant.created mit status: "Delivered", da ein bei der Erstellung zugestellter Grant kein delivered-Ereignis auslöst.
Ordne revocation_reason den Retention-Flows zu. Ein subscription_on_hold-Revoke bedeutet normalerweise, dass die Karte des Kunden fehlgeschlagen ist und beim nächsten Verlängerungsvorgang erneut Zugriff gewährt wird. Ein manual- oder subscription_cancelled-Revoke ist beabsichtigt. Berücksichtige diesen Unterschied in der Kundenkommunikation.
Erkenne Duplikate anhand des webhook-id-Headers, nicht anhand des Grant-id. Ein Grant sendet created nur einmal, aber delivered und revoked können jeweils mehrmals ausgelöst werden, da ein widerrufener Grant wiederhergestellt und erneut widerrufen werden kann. failed ist ebenfalls nicht immer endgültig: Ein fehlgeschlagener OAuth-Grant kann dennoch zugestellt werden. Erneute Zustellungen durch das Webhook-System können ebenfalls zu einer Wiederholung eines Ereignisses führen. Überspringe Wiederholungen anhand von webhook-id und verwende für deine eigenen Grant-Datensätze den Grant-id als Schlüssel.
Lies integration_type, um den Grant-Typ zu erkennen. Der Payload enthält integration_type direkt (zum Beispiel license_key, digital_files, discord). Die verschachtelten Objekte license_key und digital_product_delivery werden ausgefüllt, sobald die jeweiligen Grants zugestellt wurden; ein manuell erfüllter License-Key-Grant bleibt Pending mit integration_type: "license_key" und einem null license_key, bis du ihn erfüllst.
Zeige bei OAuth-basierten Grants oauth_url dem Kunden an. Das entitlement_grant.created-Ereignis für Subscriber-Flows von Discord, GitHub oder Notion kann ein oauth_url und ein oauth_expires_at enthalten. Wenn es null ist, warte auf ein späteres Ereignis oder leite den Kunden zum Customer Portal weiter. Sende die URL per E-Mail an den Kunden oder zeige sie in deiner App an, um die Zustellung zu ermöglichen.

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

brand_id

string

erforderlich

Brand id this grant belongs to.

business_id

string

erforderlich

Identifier of the business that owns the grant.

created_at

string<date-time>

erforderlich

Timestamp when the grant was created.

customer_id

string

erforderlich

Identifier of the customer the grant was issued to.

entitlement_id

string

erforderlich

Identifier of the entitlement this grant was issued from.

string

erforderlich

Unique identifier of the grant.

integration_type

enum<string>

erforderlich

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

Verfügbare Optionen:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

erforderlich

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

erforderlich

Lifecycle status of the grant.

Verfügbare Optionen:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

erforderlich

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