Concessão de Direitos
A carga útil enviada para seu endpoint de webhook quando uma concessão de direito é criada, entregue, falha ou é revogada.
Eventos de Webhook para Concessão de Direitos
Esses eventos são disparados sempre que a concessão de direitos de um cliente altera o estado, por exemplo, quando uma chave de licença é gerada, um papel do Discord é atribuído, um link de download é provisionado ou o acesso é revogado. Assine esses eventos para manter sua aplicação sincronizada com o que cada cliente pode acessar.EntitlementGrantResponse documentada no esquema abaixo.
Desencadeadores de Eventos
entitlement_grant.created
Uma linha de concessão foi inserida. A concessão sempre tem umid estável a partir deste ponto, mesmo que seu status mude. Use este evento para registrar que o cumprimento está em andamento.
Para license keys preenchidas automaticamente, a linha é inserida diretamente com status: "Delivered" e delivered_at preenchidos, portanto um único evento created não é seguido por outras alterações de estado, a menos que o grant seja posteriormente revogado.
Para license keys preenchidas manualmente (entitlements com fulfillment_mode: manual), a linha chega com status: "Pending" e sem o objeto license_key — ainda não há uma key. Esse evento indica que uma key está aguardando preenchimento; forneça-a por meio de POST /grants/{grant_id}/license-key, que então dispara entitlement_grant.delivered. Consulte Manual Fulfillment.
Para todas as outras integrações, a linha chega com status: "Pending". Um evento delivered ou failed ocorre quando a entrega é concluída:
- Integrações baseadas em OAuth (Discord, GitHub, Notion) incluem um
oauth_urlque o cliente deve acessar para concluir o consentimento. O grant permanecePendingaté que o cliente autorize. - Integrações diretas com a plataforma (Telegram, Framer, Digital Files) permanecem em
Pendingapenas brevemente enquanto a chamada à plataforma é executada e, em seguida, passam paraDelivered.
pending para delivered. O cliente agora tem o acesso descrito pela concessão. Use este evento para desbloquear funcionalidades dependentes em seus próprios sistemas, por exemplo, para provisionar um espaço de trabalho, enviar um email de boas-vindas personalizado, ou marcar uma bandeira “cumprida”.
O grant fez a transição de Pending para Delivered. O cliente agora tem o acesso descrito pelo entitlement. Use esse evento para desbloquear funcionalidades dependentes nos seus próprios sistemas, por exemplo, para provisionar um workspace, enviar um e-mail de boas-vindas personalizado ou marcar uma flag de “fulfilled”.
O campo delivered_at do payload registra quando a entrega foi concluída. Para grants que chegaram em Delivered na criação, você receberá os eventos created e delivered em sequência.
A entrega foi tentada e falhou com um erro não reativável. Os campos error_code e error_message explicam a falha. Causas comuns incluem um token OAuth revogado, uma permissão de plataforma negada ou um alvo ausente (por exemplo, uma guilda do Discord excluída).
entitlement_grant.revoked
O acesso foi retirado no nível da plataforma: papel do Discord removido, colaborador do GitHub removido, chave de licença desativada, URLs de download de arquivos não são mais emitidos. O camporevocation_reason registra o disparador.
Variantes de Carga Útil
O campodata é sempre um objeto EntitlementGrantResponse. Dois tipos de integração anexam objetos aninhados extras:
O campo data é sempre um objeto EntitlementGrantResponse. O payload contém um campo integration_type (por exemplo, license_key, digital_files, discord) para que você possa reconhecer diretamente o tipo de grant. Três tipos de integração também incluem objetos aninhados adicionais:
license_keyé incluído quandointegration_typeélicense_keye uma key foi emitida. Ele contém a key gerada, a expiração e o uso de ativação. Para um grant preenchido manualmente que ainda está emPending, esse objeto énullaté que você preencha o grant.digital_product_deliveryé incluído quandointegration_typeédigital_files. Ele contém URLs de download pré-assinadas, oinstructionsopcional e oexternal_urlopcional.featureé incluído quandointegration_typeéfeature_flag. Ele contém ofeature_typee ofeature_idda capacidade concedida pelo grant.
null; a configuração relevante é registrada no próprio entitlement, não no grant.
Exemplos de Carga Útil
Chave de licença entregue (entitlement_grant.delivered)
fulfillment_mode: manual. O grant está Pending sem um objeto license_key — o merchant deve fornecer a key.
Concessão revogada no cancelamento da assinatura (entitlement_grant.revoked)
Entrega falhou (entitlement_grant.failed)
- Aguarde
entitlement_grant.deliveredantes de desbloquear funcionalidades dependentes. Um eventopayment.succeededindica que o pagamento foi processado; ele não informa se o cliente já tem o repositório GitHub ou o papel Discord. O eventodeliveredé a fonte da verdade para o cumprimento. - Mapeie
revocation_reasonpara fluxos de retenção. Uma revogaçãosubscription_on_holdgeralmente significa que o cartão do cliente falhou e a próxima renovação reativará o acesso. Uma revogaçãomanualousubscription_cancelledé intencional. Trate-os de forma diferente na comunicação com o cliente. - Use a concessão
idcomo sua chave de idempotência. Uma única concessão emite no máximo um eventocreatede no máximo um evento terminal (deliveredoufailed), e no máximo um eventorevoked. As re-entregas do sistema de webhook podem repetir eventos; deduplique na concessãoidmaistype. - Inspecione
license_keyedigital_product_deliverypara reconhecer o tipo de integração. A própria carga útil da concessão não transporta o tipo de integração, mas exatamente um desses objetos aninhados é preenchido para concessões de chave de licença e arquivos digitais. - Para concessões baseadas em OAuth, exiba
oauth_urlao cliente. O eventoentitlement_grant.createdpara fluxos de assinantes do Discord, GitHub ou Notion inclui umoauth_urleoauth_expires_at. Envie por email ao cliente ou exiba em seu aplicativo para desbloquear a entrega.
Dicas de integração
- Aguarde
entitlement_grant.deliveredantes de desbloquear funcionalidades dependentes. Um eventopayment.succeededinforma que o pagamento foi compensado; ele não informa que o cliente já tem o repositório do GitHub ou a função no Discord. O eventodeliveredé a fonte de verdade para o preenchimento. - Associe
revocation_reasonaos fluxos de retenção. Uma revogaçãosubscription_on_holdgeralmente significa que o cartão do cliente falhou e a próxima renovação concederá o acesso novamente. Uma revogaçãomanualousubscription_cancelledé intencional. Trate-as de forma diferente nas mensagens ao cliente. - Use
iddo grant como sua idempotency key. Um único grant emite no máximo um eventocreated, no máximo um evento terminal (deliveredoufailed) e no máximo um eventorevoked. As reentregas do sistema de webhook podem repetir eventos; elimine duplicatas usandoiddo grant junto comtype. - Leia
integration_typepara reconhecer o tipo de grant. O payload contémintegration_typediretamente (por exemplo,license_key,digital_files,discord). Os objetos aninhadoslicense_keyedigital_product_deliverysão preenchidos quando seus respectivos grants são entregues; um grant de license key preenchido manualmente permanecePendingcomintegration_type: "license_key"e umnulllicense_keyaté que você o preencha. - Para grants baseados em OAuth, mostre
oauth_urlao cliente. O eventoentitlement_grant.createdpara fluxos de assinantes do Discord, GitHub ou Notion incluioauth_urleoauth_expires_at. Envie-o por e-mail ao cliente ou mostre-o no seu app para desbloquear a 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.