Skip to main content

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. Los cuatro eventos comparten la misma carga útil EntitlementGrantResponse documentada en el esquema a continuación.

Desencadenantes de Eventos

entitlement_grant.created

Se acaba de insertar una fila de concesión. La concesión siempre tiene un id estable desde este punto en adelante, incluso si su estado cambia. Use este evento para registrar que el cumplimiento está en progreso. Para las license keys auto-fulfilladas, 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:
  • Las integraciones basadas en OAuth (Discord, GitHub, Notion) incluyen un oauth_url que el cliente debe visitar para completar el consentimiento. El grant permanece en Pending hasta que el cliente autoriza.
  • Las integraciones directas con la plataforma (Telegram, Framer, Digital Files) permanecen brevemente en Pending mientras se ejecuta la llamada a la plataforma y luego 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ó de Pending a Delivered. El cliente ahora tiene el acceso descrito por el entitlement. Usa este evento para desbloquear funciones dependientes en tus propios sistemas, por ejemplo, para aprovisionar un espacio de trabajo, 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. Para los grants que llegaron en Delivered al crearse, recibirás los eventos created y delivered consecutivamente. 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.

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)

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.

Concesión revocada por cancelación de suscripción (entitlement_grant.revoked)

Entrega fallida (entitlement_grant.failed)


  • Espere entitlement_grant.delivered antes de desbloquear funciones dependientes. Un evento payment.succeeded le indica que el dinero se transfirió; no le indica que el cliente ya tiene el repositorio de GitHub o el rol de Discord. El evento delivered es la fuente de verdad para el cumplimiento.
  • Mapee revocation_reason a flujos de retención. Una revocación subscription_on_hold generalmente significa que la tarjeta del cliente falló y la próxima renovación re-otorgará el acceso. Una revocación manual o subscription_cancelled es intencional. Trátelos de manera diferente en la mensajería al cliente.
  • Utilice la concesión id como su clave de idempotencia. Una sola concesión emite como máximo un evento created y como máximo un evento terminal (delivered o failed), y como máximo un evento revoked. Las re-entregas del sistema de webhook pueden repetir eventos; dedupe en la concesión id más type.
  • Inspeccione license_key e digital_product_delivery para reconocer el tipo de integración. La carga útil de la concesión en sí no lleva el tipo de integración, pero exactamente uno de estos objetos anidados se completa para derechos de clave de licencia y archivos digitales.
  • Para concesiones basadas en OAuth, haga visible oauth_url al cliente. El evento entitlement_grant.created para flujos de suscripción de Discord, GitHub, o Notion incluye un oauth_url e oauth_expires_at. Envíelo por correo electrónico al cliente o muéstrelo en su aplicación para desbloquear la entrega.

Consejos de Integración

  • Espera a entitlement_grant.delivered antes de desbloquear funciones dependientes. Un evento payment.succeeded indica que el pago se liquidó; no indica que el cliente ya tenga el repositorio de GitHub o el rol de Discord. El evento delivered es la fuente de verdad para el fulfillment.
  • Asocia revocation_reason con los flujos de retención. Una revocación subscription_on_hold normalmente significa que la tarjeta del cliente falló y que la próxima renovación volverá a concederle acceso. Una revocación manual o subscription_cancelled es intencionada. Trátalas de forma diferente en los mensajes al cliente.
  • Usa id del grant como tu clave de idempotencia. Un único grant emite como máximo un evento created y como máximo un evento terminal (delivered o failed), además de como máximo un evento revoked. Las reentregas del sistema de webhooks pueden repetir eventos; elimina duplicados usando id del grant más type.
  • Lee integration_type para reconocer 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 rellenan cuando se entregan sus respectivos grants; un grant de license key fulfillado manualmente permanece en Pending con integration_type: "license_key" y un null license_key hasta que completes su fulfillment.
  • Para los grants basados en OAuth, muestra oauth_url al cliente. El evento entitlement_grant.created para los flujos de suscripción de Discord, GitHub o Notion incluye oauth_url y oauth_expires_at. Envíalo por correo electrónico al cliente o muéstralo 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.

id
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.

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.

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.

license_key
null | object

License-key delivery payload, present when the entitlement integration is license_key.

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.

Última modificación el 21 de agosto de 2026