Octroi de droits

Événements Webhook d’Octroi de Droits

Ces événements se déclenchent chaque fois que l’état de l’octroi de droits d’un client change, par exemple lorsqu’une clé de licence est générée, un rôle Discord est attribué, un lien de téléchargement est provisionné, ou l’accès est révoqué. Abonnez-vous à ces événements pour garder votre application synchronisée avec ce à quoi chaque client peut accéder.

Event	Description
`entitlement_grant.created`	Une nouvelle ligne d’attribution a été créée. Le statut est `Delivered` immédiatement pour les clés de licence et les indicateurs de fonctionnalité traités automatiquement, et `Pending` pour les clés de licence traitées manuellement et toutes les autres intégrations.
`entitlement_grant.delivered`	L’attribution passe à l’état livré. Le client a désormais accès à la plateforme, au fichier ou à la clé de licence accordé(e).
`entitlement_grant.failed`	La livraison a échoué et ne fera pas l’objet d’une nouvelle tentative. Examinez `error_code` et `error_message`.
`entitlement_grant.revoked`	L’accès a été retiré. Examinez `revocation_reason` pour comprendre pourquoi.

Les quatre événements partagent la même charge utile EntitlementGrantResponse documentée dans le schéma ci-dessous.

Déclencheurs d’Événements

entitlement_grant.created

Une ligne d’attribution a été insérée. L’attribution possède toujours un id stable à partir de ce moment, même si son statut change. Utilisez cet événement pour enregistrer que la mise à disposition est en cours. Pour les clés de licence traitées automatiquement et les indicateurs de fonctionnalité, la ligne est insérée directement avec status: "Delivered" et delivered_at renseignés. Ainsi, un seul événement created est suivi d’aucun autre changement d’état, sauf si l’attribution est révoquée ultérieurement. Pour les clés de licence traitées manuellement (entitlements avec fulfillment_mode: manual), la ligne arrive avec status: "Pending" et sans objet license_key — aucune clé n’est encore disponible. Cet événement vous indique qu’une clé attend d’être traitée ; fournissez-la via POST /grants/{grant_id}/license-key, ce qui déclenche ensuite entitlement_grant.delivered. Consultez Traitement manuel. Pour toutes les autres intégrations, la ligne arrive avec status: "Pending". Un événement delivered ou failed suit une fois la livraison terminée :

Les intégrations basées sur OAuth (Discord, GitHub, Notion) utilisent une oauth_url que le client doit consulter pour terminer son consentement. Dodo Payments essaie de la créer lorsque l’autorisation est créée ; entitlement_grant.created peut donc l’inclure. Si elle est null, elle est renseignée lorsque le client démarre le flux d’acceptation depuis le Customer Portal. L’autorisation reste Pending jusqu’à ce que le client l’autorise.
Les intégrations directes avec la plateforme (Telegram, Framer, Digital Files) restent Pending uniquement pendant l’exécution de l’appel à la plateforme, puis passent à Delivered.

entitlement_grant.delivered

L’attribution est passée à Delivered, généralement depuis Pending. Le client dispose désormais de l’accès décrit par le droit. Utilisez cet événement pour déverrouiller les fonctionnalités dépendantes dans vos propres systèmes, par exemple pour provisionner un espace de travail, envoyer un e-mail de bienvenue personnalisé ou marquer un indicateur « fulfilled ». Le champ delivered_at de la charge utile indique le moment où la livraison a été terminée. delivered est déclenché chaque fois que le statut d’une attribution existante passe à Delivered : depuis Pending, lorsqu’une attribution OAuth ayant échoué réussit ultérieurement, ou lorsqu’une attribution révoquée est restaurée. Une attribution qui arrive à l’état Delivered lors de sa création, comme une clé de licence traitée automatiquement, ne déclenche que created.

entitlement_grant.failed

La livraison a été tentée et a échoué avec une erreur non réessayer. Les champs error_code et error_message expliquent l’échec. Les causes courantes incluent un token OAuth révoqué, une permission de plateforme refusée, ou une cible manquante (par exemple, un serveur Discord supprimé).

Traitez entitlement_grant.failed comme une action à entreprendre. Le client a payé mais n’a pas obtenu d’accès. Signalez les échecs à votre équipe de support ou déclenchez une nouvelle subvention une fois que le problème sous-jacent est résolu.

entitlement_grant.revoked

L’accès a été retiré au niveau de la plateforme : rôle Discord supprimé, collaborateur GitHub supprimé, clé de licence désactivée, URL de téléchargement de fichiers non émises. Le champ revocation_reason enregistre le déclencheur.

`revocation_reason`	Déclencheur
`subscription_cancelled`	L’abonnement du client a été annulé (événement `subscription.cancelled`).
`subscription_on_hold`	L’abonnement est suspendu en raison de l’échec du renouvellement (`subscription.on_hold`). Récupérable : une nouvelle tentative réussie entraîne une nouvelle attribution.
`subscription_paused`	L’abonnement a été mis en pause (`subscription.paused`). Récupérable : la reprise entraîne une nouvelle attribution.
`subscription_expired`	L’abonnement est arrivé à terme (`subscription.expired`).
`plan_changed`	Le plan a été modifié ; les anciennes attributions sont révoquées avant l’émission des nouvelles (`subscription.plan_changed`).
`refund`	Un remboursement a été traité pour le paiement unique initial (`refund.succeeded`).
`manual`	Un marchand a révoqué l’attribution via l’API ou le tableau de bord. Les révocations manuelles ne font pas l’objet d’une nouvelle attribution automatique lors du renouvellement de l’abonnement.
`license_key_disabled`	La clé de licence associée à une attribution de clé de licence a été désactivée. L’attribution est réactivée automatiquement si la clé est réactivée.
`platform_external`	La partie plateforme d’une intégration n’était plus synchronisée (par exemple, un rôle Discord a été supprimé manuellement, l’application GitHub a perdu l’accès au dépôt ou une vérification de rapprochement a détecté une cible manquante). L’attribution ne fait pas l’objet d’une nouvelle attribution automatique lors du renouvellement de l’abonnement tant que le problème de plateforme sous-jacent n’est pas résolu.

Variantes de charge utile

Le champ data est toujours un objet EntitlementGrantResponse. Le payload contient un champ integration_type (par exemple license_key, digital_files, discord), afin que vous puissiez reconnaître directement le type de grant. Trois types d’intégration ajoutent également des objets imbriqués supplémentaires :

license_key est inclus lorsque integration_type vaut license_key et qu’une clé a été émise. Il contient la clé générée, sa date d’expiration et les informations d’utilisation pour son activation. Pour un grant traité manuellement qui se trouve encore dans Pending, cet objet vaut null jusqu’à ce que vous traitiez le grant.
digital_product_delivery est inclus lorsque integration_type vaut digital_files. Il contient des URL de téléchargement présignées, le champ facultatif instructions et le champ facultatif external_url.
feature est inclus lorsque integration_type vaut feature_flag. Il contient feature_type et feature_id de la capacité accordée par le grant.

Pour tous les autres types d’intégration (Discord, GitHub, Telegram, Figma, Framer, Notion), ces champs imbriqués valent null ; la configuration pertinente est enregistrée dans l’entitlement lui-même, et non dans le grant.

Charges utiles d’exemple

Clé de licence livrée (`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"
  }
}

Clé de licence en attente de traitement manuel (`entitlement_grant.created`)

Déclenché lorsqu’un client achète un produit dont l’entitlement License Key utilise fulfillment_mode: manual. Le grant est Pending et ne contient encore aucun objet license_key — le marchand doit fournir la clé.

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

Fichiers numériques livrés (`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"
  }
}

Rôle Discord créé et en attente (`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"
  }
}

Attribution révoquée lors de l’annulation de l’abonnement (`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"
  }
}

Échec de la livraison (`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"
  }
}

Conseils d’intégration

Déverrouillez les fonctionnalités dépendantes lorsqu’une autorisation atteint Delivered. Un événement payment.succeeded vous indique que le paiement a été compensé ; il ne vous indique pas que le client dispose déjà du dépôt GitHub ou du rôle Discord. Gérez entitlement_grant.delivered, ainsi que entitlement_grant.created avec status: "Delivered", car une autorisation délivrée lors de sa création ne déclenche aucun événement delivered.
Associez revocation_reason aux flux de fidélisation. Une révocation subscription_on_hold signifie généralement que la carte du client a échoué et que le prochain renouvellement rétablira l’accès. Une révocation manual ou subscription_cancelled est intentionnelle. Traitez-les différemment dans vos communications avec les clients.
Détectez les doublons avec l’en-tête webhook-id, et non avec le id de l’autorisation. Une autorisation émet created une seule fois, mais delivered et revoked peuvent chacun être déclenchés plusieurs fois, car une autorisation révoquée peut être restaurée puis révoquée à nouveau. failed n’est pas toujours définitif non plus : une autorisation OAuth ayant échoué peut tout de même être délivrée. Les nouvelles livraisons du système de webhooks peuvent également répéter un événement. Ignorez les répétitions à l’aide de webhook-id et utilisez le id de l’autorisation comme clé pour vos propres enregistrements.
Lisez integration_type pour identifier le type d’autorisation. Le payload contient directement integration_type (par exemple license_key, digital_files, discord). Les objets imbriqués license_key et digital_product_delivery sont renseignés une fois leurs autorisations respectives délivrées ; une autorisation de clé de licence traitée manuellement reste Pending avec integration_type: "license_key" et une null license_key jusqu’à ce que vous la traitiez.
Présentez oauth_url au client pour les autorisations basées sur OAuth. L’événement entitlement_grant.created des flux d’abonnement Discord, GitHub ou Notion peut inclure une oauth_url et oauth_expires_at. Si elle est null, attendez un événement ultérieur ou redirigez le client vers le Customer Portal. Envoyez l’URL au client par e-mail ou affichez-la dans votre application pour débloquer la livraison.

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

brand_id

string

requis

Brand id this grant belongs to.

business_id

string

requis

Identifier of the business that owns the grant.

created_at

string<date-time>

requis

Timestamp when the grant was created.

customer_id

string

requis

Identifier of the customer the grant was issued to.

entitlement_id

string

requis

Identifier of the entitlement this grant was issued from.

string

requis

Unique identifier of the grant.

integration_type

enum<string>

requis

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

Options disponibles:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

requis

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

requis

Lifecycle status of the grant.

Options disponibles:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

requis

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

Événements Webhook d’Octroi de Droits

Déclencheurs d’Événements

entitlement_grant.created

entitlement_grant.delivered

entitlement_grant.failed

entitlement_grant.revoked

Variantes de charge utile

Charges utiles d’exemple

Clé de licence livrée (`entitlement_grant.delivered`)

Clé de licence en attente de traitement manuel (`entitlement_grant.created`)

Fichiers numériques livrés (`entitlement_grant.delivered`)

Rôle Discord créé et en attente (`entitlement_grant.created`)

Attribution révoquée lors de l’annulation de l’abonnement (`entitlement_grant.revoked`)

Échec de la livraison (`entitlement_grant.failed`)

Conseils d’intégration

​Événements Webhook d’Octroi de Droits

​Déclencheurs d’Événements

​entitlement_grant.created

​entitlement_grant.delivered

​entitlement_grant.failed

​entitlement_grant.revoked

​Variantes de charge utile

​Charges utiles d’exemple

​Clé de licence livrée (entitlement_grant.delivered)

​Clé de licence en attente de traitement manuel (entitlement_grant.created)

​Fichiers numériques livrés (entitlement_grant.delivered)

​Rôle Discord créé et en attente (entitlement_grant.created)

​Attribution révoquée lors de l’annulation de l’abonnement (entitlement_grant.revoked)

​Échec de la livraison (entitlement_grant.failed)

​Conseils d’intégration

Événements Webhook d’Octroi de Droits

Déclencheurs d’Événements

entitlement_grant.created

entitlement_grant.delivered

entitlement_grant.failed

entitlement_grant.revoked

Variantes de charge utile

Charges utiles d’exemple

Clé de licence livrée (`entitlement_grant.delivered`)

Clé de licence en attente de traitement manuel (`entitlement_grant.created`)

Fichiers numériques livrés (`entitlement_grant.delivered`)

Rôle Discord créé et en attente (`entitlement_grant.created`)

Attribution révoquée lors de l’annulation de l’abonnement (`entitlement_grant.revoked`)

Échec de la livraison (`entitlement_grant.failed`)

Conseils d’intégration