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 de grant a été créée. Le statut est `Delivered` immédiatement pour les clés de licence traitées automatiquement, et `Pending` pour les clés de licence traitées manuellement et toutes les autres intégrations.
`entitlement_grant.delivered`	Le grant passe à l’état livré. Le client a désormais accès à la plateforme, au fichier ou à la clé de licence autorisé.
`entitlement_grant.failed`	La livraison a échoué et ne fera pas l’objet d’une nouvelle tentative. Inspectez `error_code` et `error_message`.
`entitlement_grant.revoked`	L’accès a été retiré. Inspectez `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’octroi vient d’être insérée. L’octroi a toujours une id stable à partir de ce moment, même si son statut change. Utilisez cet événement pour enregistrer que l’exécution est en cours. Pour les clés de licence traitées automatiquement, la ligne est insérée directement avec status: "Delivered" et delivered_at renseignés. Ainsi, un unique événement created est suivi d’aucune autre modification d’état, sauf si le grant est révoqué 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 :

Intégrations basées sur OAuth (Discord, GitHub, Notion) incluent un oauth_url que le client doit consulter pour terminer son consentement. Le grant reste Pending jusqu’à l’autorisation du client.
Intégrations directes à la plateforme (Telegram, Framer, Digital Files) restent brièvement dans Pending pendant l’exécution de l’appel à la plateforme, puis passent à Delivered.

entitlement_grant.delivered

Le grant est passé de Pending à Delivered. Le client dispose désormais de l’accès décrit par l’entitlement. 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 du payload indique quand la livraison s’est terminée. Pour les grants arrivés à l’état Delivered dès leur création, vous recevrez les événements created et delivered consécutivement.

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.
`SubscriptionPaused`	L’abonnement a été mis en pause (`subscription.paused`). Récupérable : la reprise entraîne une nouvelle attribution.
`subscription_expired`	L’abonnement a atteint la fin de sa période (`subscription.expired`).
`plan_changed`	Le plan a été modifié ; les attributions précédentes 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 automatiquement réactivée si la clé est réactivée.
`platform_external`	Le côté plateforme d’une intégration n’était plus synchronisé (par exemple, un rôle Discord a été supprimé manuellement, la GitHub App 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 la plateforme sous-jacente 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 dé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": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "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": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-05-01T10:25:33Z"
  }
}

Clé de licence en attente de réalisation manuelle (`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": null,
    "created_at": "2026-05-01T10:24:00Z",
    "updated_at": "2026-05-01T10:24:00Z"
  }
}

Fichiers numériques dé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": null,
    "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": null,
    "created_at": "2026-05-01T10:31:00Z",
    "updated_at": "2026-05-01T10:31:00Z"
  }
}

Subvention révoquée lors de l’annulation d’un 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": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "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": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-06-15T08:12:44Z"
  }
}

Livraison échouée (`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": null,
    "created_at": "2026-05-01T10:36:00Z",
    "updated_at": "2026-05-01T10:36:21Z"
  }
}

Conseils d’intégration

Attendez entitlement_grant.delivered avant de déverrouiller les fonctionnalités dépendantes. Un événement payment.succeeded vous indique que le paiement a été confirmé ; il ne signifie pas que le client dispose déjà du dépôt GitHub ou du rôle Discord. L’événement delivered fait foi pour le traitement.
Associez revocation_reason aux flux de rétention. 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.
Utilisez id du grant comme clé d’idempotence. Un même grant émet au maximum un événement created et au maximum un événement terminal (delivered ou failed), ainsi qu’au maximum un événement revoked. Les nouvelles livraisons du système de webhook peuvent répéter les événements ; dédupliquez-les avec id du grant et type.
Lisez integration_type pour reconnaître le type de grant. 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 grants respectifs livrés ; un grant de clé de licence traité manuellement reste Pending avec integration_type: "license_key" et un null license_key jusqu’à ce que vous le traitiez.
Pour les grants OAuth, présentez oauth_url au client. L’événement entitlement_grant.created pour les flux d’abonnement Discord, GitHub ou Notion inclut oauth_url et oauth_expires_at. Envoyez-le par e-mail au client ou affichez-le 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.

Dernière modification le 21 août 2026

{
  "brand_id": "<string>",
  "business_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "entitlement_id": "<string>",
  "id": "<string>",
  "metadata": {},
  "updated_at": "2023-11-07T05:31:56Z",
  "delivered_at": "2023-11-07T05:31:56Z",
  "digital_product_delivery": {
    "files": [
      {
        "download_url": "<string>",
        "expires_in": 123,
        "file_id": "<string>",
        "filename": "<string>",
        "content_type": "<string>",
        "file_size": 123
      }
    ],
    "external_url": "<string>",
    "instructions": "<string>"
  },
  "error_code": "<string>",
  "error_message": "<string>",
  "feature": {
    "feature_id": "<string>",
    "feature_type": "boolean"
  },
  "license_key": {
    "activations_used": 123,
    "key": "<string>",
    "activations_limit": 123,
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "oauth_expires_at": "2023-11-07T05:31:56Z",
  "oauth_url": "<string>",
  "payment_id": "<string>",
  "revocation_reason": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "subscription_id": "<string>"
}

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 délivrée (`entitlement_grant.delivered`)

Clé de licence en attente de réalisation manuelle (`entitlement_grant.created`)

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

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

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

Livraison échouée (`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 délivrée (entitlement_grant.delivered)

​Clé de licence en attente de réalisation manuelle (entitlement_grant.created)

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

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

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

​Livraison échouée (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 délivrée (`entitlement_grant.delivered`)

Clé de licence en attente de réalisation manuelle (`entitlement_grant.created`)

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

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

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

Livraison échouée (`entitlement_grant.failed`)

Conseils d’intégration