Concesión de Derechos
La carga útil enviada a su endpoint de webhook cuando se crea, entrega, falla o revoca una 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.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 unid 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_urlque el cliente debe visitar para completar el consentimiento. El grant permanece enPendinghasta que el cliente autoriza. - Las integraciones directas con la plataforma (Telegram, Framer, Digital Files) permanecen brevemente en
Pendingmientras se ejecuta la llamada a la plataforma y luego pasan aDelivered.
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).
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 camporevocation_reason registra el desencadenante.
Variantes de Carga Útil
El campodata 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_keyse incluye cuandointegration_typeeslicense_keyy 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á enPending, este objeto esnullhasta que completes el fulfillment del grant.digital_product_deliveryse incluye cuandointegration_typeesdigital_files. Contiene URLs de descarga presignadas, elinstructionsopcional y elexternal_urlopcional.featurese incluye cuandointegration_typeesfeature_flag. Contiene elfeature_typey elfeature_idde la capacidad otorgada por el grant.
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)
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.deliveredantes de desbloquear funciones dependientes. Un eventopayment.succeededle indica que el dinero se transfirió; no le indica que el cliente ya tiene el repositorio de GitHub o el rol de Discord. El eventodeliveredes la fuente de verdad para el cumplimiento. - Mapee
revocation_reasona flujos de retención. Una revocaciónsubscription_on_holdgeneralmente significa que la tarjeta del cliente falló y la próxima renovación re-otorgará el acceso. Una revocaciónmanualosubscription_cancelledes intencional. Trátelos de manera diferente en la mensajería al cliente. - Utilice la concesión
idcomo su clave de idempotencia. Una sola concesión emite como máximo un eventocreatedy como máximo un evento terminal (deliveredofailed), y como máximo un eventorevoked. Las re-entregas del sistema de webhook pueden repetir eventos; dedupe en la concesiónidmástype. - Inspeccione
license_keyedigital_product_deliverypara 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_urlal cliente. El eventoentitlement_grant.createdpara flujos de suscripción de Discord, GitHub, o Notion incluye unoauth_urleoauth_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.deliveredantes de desbloquear funciones dependientes. Un eventopayment.succeededindica que el pago se liquidó; no indica que el cliente ya tenga el repositorio de GitHub o el rol de Discord. El eventodeliveredes la fuente de verdad para el fulfillment. - Asocia
revocation_reasoncon los flujos de retención. Una revocaciónsubscription_on_holdnormalmente significa que la tarjeta del cliente falló y que la próxima renovación volverá a concederle acceso. Una revocaciónmanualosubscription_cancelledes intencionada. Trátalas de forma diferente en los mensajes al cliente. - Usa
iddel grant como tu clave de idempotencia. Un único grant emite como máximo un eventocreatedy como máximo un evento terminal (deliveredofailed), además de como máximo un eventorevoked. Las reentregas del sistema de webhooks pueden repetir eventos; elimina duplicados usandoiddel grant mástype. - Lee
integration_typepara reconocer el tipo de grant. El payload incluyeintegration_typedirectamente (por ejemplo,license_key,digital_files,discord). Los objetos anidadoslicense_keyydigital_product_deliveryse rellenan cuando se entregan sus respectivos grants; un grant de license key fulfillado manualmente permanece enPendingconintegration_type: "license_key"y unnulllicense_keyhasta que completes su fulfillment. - Para los grants basados en OAuth, muestra
oauth_urlal cliente. El eventoentitlement_grant.createdpara los flujos de suscripción de Discord, GitHub o Notion incluyeoauth_urlyoauth_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 this grant belongs to.
Identifier of the business that owns the grant.
Timestamp when the grant was created.
Identifier of the customer the grant was issued to.
Identifier of the entitlement this grant was issued from.
Unique identifier of the grant.
The integration type of the grant's entitlement (e.g. license_key).
discord, telegram, github, figma, framer, notion, digital_files, license_key, feature_flag Arbitrary key-value metadata recorded on the grant.
Lifecycle status of the grant.
Pending, Delivered, Failed, Revoked Timestamp when the grant was last modified.
Timestamp when the grant transitioned to delivered, when applicable.
Digital-product-delivery payload, present when the entitlement
integration is digital_files.
Machine-readable code reported when delivery failed, when applicable.
Human-readable message reported when delivery failed, when applicable.
Typed feature payload, present only when the entitlement integration is
feature_flag; null for every other integration type.
License-key delivery payload, present when the entitlement integration
is license_key.
Timestamp when oauth_url stops being valid, when applicable.
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.
Identifier of the payment that triggered this grant, when applicable.
Reason recorded when the grant was revoked, when applicable.
Timestamp when the grant transitioned to revoked, when applicable.
Identifier of the subscription that triggered this grant, when applicable.