Concesión de Derechos

Eventos de Webhook para Concesión de Derechos

Estos eventos se activan cada vez que cambia el estado de la concesión de derechos de un cliente, por ejemplo, cuando se genera una clave de licencia, se asigna un rol de Discord, se proporciona un enlace de descarga, o se revoca el acceso. Suscríbase a estos eventos para mantener su aplicación sincronizada con lo que cada cliente puede acceder.

Evento	Descripción
`entitlement_grant.created`	Se creó una nueva fila de grant. El estado es `Delivered` inmediatamente para license keys cumplimentadas automáticamente y feature flags, y `Pending` para license keys cumplimentadas manualmente y cualquier otra integración.
`entitlement_grant.delivered`	El grant pasa al estado delivered. El cliente ahora tiene acceso a la plataforma, el archivo o la license key incluidos en la entitlement.
`entitlement_grant.failed`	La entrega falló y no se volverá a intentar. Inspecciona `error_code` y `error_message`.
`entitlement_grant.revoked`	Se retiró el acceso. Inspecciona `revocation_reason` para entender el motivo.

Los cuatro eventos comparten la misma carga útil EntitlementGrantResponse documentada en el esquema a continuación.

Desencadenantes de Eventos

entitlement_grant.created

Se insertó una fila de grant. A partir de este momento, el grant siempre tiene un id estable, incluso si su estado cambia. Usa este evento para registrar que la cumplimentación está en curso. Para license keys cumplimentadas automáticamente y feature flags, la fila se inserta directamente con status: "Delivered" y delivered_at rellenados, por lo que a un único evento created no le siguen más cambios de estado, a menos que el grant se revoque posteriormente. Para las license keys fulfilladas manualmente (entitlements con fulfillment_mode: manual), la fila llega con status: "Pending" y sin el objeto license_key: todavía no hay ninguna key. Este evento indica que hay una key pendiente de fulfillment; proporciónala mediante POST /grants/{grant_id}/license-key, lo que activa entitlement_grant.delivered. Consulta Manual Fulfillment. Para cualquier otra integración, la fila llega con status: "Pending". Una vez completada la entrega, le sigue un evento delivered o failed:

Integraciones basadas en OAuth (Discord, GitHub, Notion) utilizan oauth_url que el cliente debe visitar para completar el consentimiento. Dodo Payments intenta crearlo cuando se crea el grant, por lo que entitlement_grant.created puede incluirlo; si es null, se completa cuando el cliente inicia el flujo de aceptación desde el Customer Portal. El grant permanece Pending hasta que el cliente autoriza.
Integraciones directas con la plataforma (Telegram, Framer, Digital Files) permanecen en Pending solo brevemente mientras se ejecuta la llamada de la plataforma; después pasan a Delivered.

La concesión pasó de pending a delivered. El cliente ahora tiene el acceso descrito por el derecho. Use este evento para desbloquear funciones dependientes en sus propios sistemas, por ejemplo, para proporcionar un espacio de trabajo, enviar un correo electrónico de bienvenida personalizado o marcar una bandera de “cumplido”. El grant pasó al estado Delivered, normalmente desde Pending. El cliente ahora tiene el acceso descrito por la entitlement. Usa este evento para desbloquear funcionalidades dependientes en tus propios sistemas, por ejemplo, para aprovisionar un workspace, enviar un correo electrónico de bienvenida personalizado o marcar un indicador de “fulfilled”. El campo delivered_at del payload registra cuándo se completó la entrega. delivered se activa cada vez que el estado de un grant existente cambia a Delivered: desde Pending, cuando un grant de OAuth fallido se completa posteriormente, o cuando se restaura un grant revocado. Un grant que llega a Delivered al crearse, como una license key cumplimentada automáticamente, solo activa created. Se intentó la entrega y falló con un error no recuperable. Los campos error_code e error_message explican la falla. Las causas comunes incluyen un token OAuth revocado, un permiso de plataforma denegado, o un destino faltante (por ejemplo, una guild de Discord eliminada).

Trate entitlement_grant.failed como accionable. El cliente pagó pero no obtuvo acceso. Haga visibles las fallas a su equipo de soporte o inicie una nueva concesión una vez que se resuelva el problema subyacente.

entitlement_grant.revoked

Se retiró el acceso a nivel de plataforma: se eliminó el rol de Discord, se eliminó el colaborador de GitHub, se desactivó la clave de licencia, las URL de descarga de archivos ya no se emiten. El campo revocation_reason registra el desencadenante.

`revocation_reason`	Desencadenante
`subscription_cancelled`	Se canceló la suscripción del cliente (evento `subscription.cancelled`).
`subscription_on_hold`	La suscripción está en espera debido a la falla en la renovación (`subscription.on_hold`). Recuperable: un reintento exitoso produce una nueva concesión.
`subscription_expired`	La suscripción alcanzó el final de su término (`subscription.expired`).
`plan_changed`	El plan cambió; las concesiones antiguas se revocan antes de emitir nuevas (`subscription.plan_changed`).
`refund`	Se procesó un reembolso para el pago único original (`refund.succeeded`).
`manual`	Un comerciante revocó la concesión a través de la API o el panel de control. Las revocaciones manuales no se otorgan nuevamente automáticamente en la renovación de la suscripción.
`license_key_disabled`	La clave de licencia detrás de una concesión de clave de licencia fue deshabilitada. La concesión se re-activa automáticamente si la clave es re-habilitada.
`platform_external`	El lado de la plataforma de una integración se desincronizó (por ejemplo, se eliminó un rol de Discord manualmente, la App de GitHub perdió acceso al repositorio, o un pase de reconciliación detectó un objetivo faltante). La concesión no se otorga automáticamente en la renovación de la suscripción hasta que se solucione el problema subyacente de la plataforma.

`revocation_reason`	Disparador
`subscription_cancelled`	La suscripción del cliente fue cancelada (evento `subscription.cancelled`).
`subscription_on_hold`	La suscripción está en espera debido a un fallo en la renovación (`subscription.on_hold`). Recuperable: un reintento exitoso produce una nueva concesión.
`subscription_paused`	La suscripción fue pausada (`subscription.paused`). Recuperable: reanudarla produce una nueva concesión.
`subscription_expired`	La suscripción llegó al final de su plazo (`subscription.expired`).
`plan_changed`	El plan cambió; las concesiones anteriores se revocan antes de emitir las nuevas (`subscription.plan_changed`).
`refund`	Se procesó un reembolso por el pago único original (`refund.succeeded`).
`manual`	Un comerciante revocó la concesión mediante la API o el panel. Las revocaciones manuales no se vuelven a conceder automáticamente al renovar la suscripción.
`license_key_disabled`	La clave de licencia asociada a una concesión de clave de licencia fue deshabilitada. La concesión se reactiva automáticamente si se vuelve a habilitar la clave.
`platform_external`	El lado de la plataforma de una integración quedó desincronizado (por ejemplo, se eliminó manualmente un rol de Discord, la GitHub App perdió acceso al repositorio o un proceso de conciliación detectó que faltaba un destino). La concesión no se vuelve a conceder automáticamente al renovar la suscripción hasta que se resuelva el problema subyacente de la plataforma.

Variantes de Carga Útil

El campo data siempre es un objeto EntitlementGrantResponse. Dos tipos de integraciones incluyen objetos anidados adicionales: El campo data siempre es un objeto EntitlementGrantResponse. El payload incluye un campo integration_type (por ejemplo, license_key, digital_files, discord) para que puedas reconocer directamente el tipo de grant. Tres tipos de integración también adjuntan objetos anidados adicionales:

license_key se incluye cuando integration_type es license_key y se ha emitido una key. Contiene la key generada, la fecha de expiración y el uso de activación. En un grant fulfillado manualmente que aún está en Pending, este objeto es null hasta que completes el fulfillment del grant.
digital_product_delivery se incluye cuando integration_type es digital_files. Contiene URLs de descarga presignadas, el instructions opcional y el external_url opcional.
feature se incluye cuando integration_type es feature_flag. Contiene el feature_type y el feature_id de la capacidad otorgada por el grant.

Para todos los demás tipos de integración (Discord, GitHub, Telegram, Figma, Framer, Notion), estos campos anidados son null; la configuración relevante se registra en el entitlement, no en el grant.

Ejemplos de Carga Útil

Clave de licencia entregada (`entitlement_grant.delivered`)

License Key Delivered (`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 Pending Manual Fulfillment (`entitlement_grant.created`)

Se activa cuando un cliente compra un producto cuyo entitlement de License Key utiliza fulfillment_mode: manual. El grant está en Pending y todavía no tiene un objeto license_key; el merchant debe proporcionar 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"
  }
}

Digital Files Delivered (`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 Role Created and Pending (`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 Revoked on Subscription Cancellation (`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 Failed (`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"
  }
}

Consejos de Integración

Desbloquea las funciones dependientes cuando un grant alcanza Delivered. Un evento payment.succeeded te indica que el dinero se liquidó; no te indica que el cliente ya tenga el repositorio de GitHub o el rol de Discord. Gestiona entitlement_grant.delivered y también entitlement_grant.created con status: "Delivered", porque un grant que se entrega al crearse no genera ningún evento delivered.
Asocia revocation_reason con los flujos de retención. Un revoke subscription_on_hold normalmente significa que la tarjeta del cliente falló y que el próximo renewal volverá a otorgar el acceso. Un revoke manual o subscription_cancelled es intencional. Trátalos de forma diferente en los mensajes al cliente.
Detecta duplicados con el header webhook-id, no con el id del grant. Un grant emite created una sola vez, pero delivered y revoked pueden activarse más de una vez, porque un grant revocado puede restaurarse y revocarse nuevamente. failed tampoco es siempre definitivo: un grant de OAuth fallido aún puede entregarse. Las reentregas del sistema de webhook también pueden repetir un evento. Omite las repeticiones mediante webhook-id y usa el id del grant como clave para tus propios registros de grants.
Lee integration_type para identificar el tipo de grant. El payload incluye integration_type directamente (por ejemplo, license_key, digital_files, discord). Los objetos anidados license_key y digital_product_delivery se completan una vez entregados sus respectivos grants; un grant de license-key cumplido manualmente permanece Pending con integration_type: "license_key" y un null license_key hasta que lo cumplas.
Para los grants basados en OAuth, muestra oauth_url al cliente. El evento entitlement_grant.created para los flujos de suscriptores de Discord, GitHub o Notion puede incluir un oauth_url y oauth_expires_at. Si es null, espera un evento posterior o dirige al cliente al Customer Portal. Envía la URL por correo electrónico al cliente o muéstrala en tu aplicación para desbloquear la entrega.

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

brand_id

string

requerido

Brand id this grant belongs to.

business_id

string

requerido

Identifier of the business that owns the grant.

created_at

string<date-time>

requerido

Timestamp when the grant was created.

customer_id

string

requerido

Identifier of the customer the grant was issued to.

entitlement_id

string

requerido

Identifier of the entitlement this grant was issued from.

string

requerido

Unique identifier of the grant.

integration_type

enum<string>

requerido

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

Opciones disponibles:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

requerido

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

requerido

Lifecycle status of the grant.

Opciones disponibles:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

requerido

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

Eventos de Webhook para Concesión de Derechos

Desencadenantes de Eventos

entitlement_grant.created

entitlement_grant.revoked

Variantes de Carga Útil

Ejemplos de Carga Útil

Clave de licencia entregada (`entitlement_grant.delivered`)

License Key Delivered (`entitlement_grant.delivered`)

License Key Pending Manual Fulfillment (`entitlement_grant.created`)

Digital Files Delivered (`entitlement_grant.delivered`)

Discord Role Created and Pending (`entitlement_grant.created`)

Grant Revoked on Subscription Cancellation (`entitlement_grant.revoked`)

Delivery Failed (`entitlement_grant.failed`)

Consejos de Integración

​Eventos de Webhook para Concesión de Derechos

​Desencadenantes de Eventos

​entitlement_grant.created

​entitlement_grant.revoked

​Variantes de Carga Útil

​Ejemplos de Carga Útil

​Clave de licencia entregada (entitlement_grant.delivered)

​License Key Delivered (entitlement_grant.delivered)

​License Key Pending Manual Fulfillment (entitlement_grant.created)

​Digital Files Delivered (entitlement_grant.delivered)

​Discord Role Created and Pending (entitlement_grant.created)

​Grant Revoked on Subscription Cancellation (entitlement_grant.revoked)

​Delivery Failed (entitlement_grant.failed)

​Consejos de Integración

Eventos de Webhook para Concesión de Derechos

Desencadenantes de Eventos

entitlement_grant.created

entitlement_grant.revoked

Variantes de Carga Útil

Ejemplos de Carga Útil

Clave de licencia entregada (`entitlement_grant.delivered`)

License Key Delivered (`entitlement_grant.delivered`)

License Key Pending Manual Fulfillment (`entitlement_grant.created`)

Digital Files Delivered (`entitlement_grant.delivered`)

Discord Role Created and Pending (`entitlement_grant.created`)

Grant Revoked on Subscription Cancellation (`entitlement_grant.revoked`)

Delivery Failed (`entitlement_grant.failed`)

Consejos de Integración