Skip to main content

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. Todos os quatro eventos compartilham a mesma carga útil EntitlementGrantResponse documentada no esquema abaixo.

Desencadeadores de Eventos

entitlement_grant.created

Uma linha de concessão foi inserida. A concessão sempre tem um id 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_url que o cliente deve acessar para concluir o consentimento. O grant permanece Pending até que o cliente autorize.
  • Integrações diretas com a plataforma (Telegram, Framer, Digital Files) permanecem em Pending apenas brevemente enquanto a chamada à plataforma é executada e, em seguida, passam para Delivered.
A concessão transitou de 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).
Trate entitlement_grant.failed como acionável. O cliente pagou mas não obteve acesso. Apresente falhas à sua equipe de suporte ou acione uma nova concessão assim que o problema subjacente for resolvido.

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 campo revocation_reason registra o disparador.

Variantes de Carga Útil

O campo data é 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 quando integration_type é license_key e 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á em Pending, esse objeto é null até que você preencha o grant.
  • digital_product_delivery é incluído quando integration_type é digital_files. Ele contém URLs de download pré-assinadas, o instructions opcional e o external_url opcional.
  • feature é incluído quando integration_type é feature_flag. Ele contém o feature_type e o feature_id da capacidade concedida pelo grant.
Para todos os outros tipos de integração (Discord, GitHub, Telegram, Figma, Framer, Notion), esses campos aninhados são 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)

Disparado quando um cliente compra um produto cujo entitlement de License Key usa 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.delivered antes de desbloquear funcionalidades dependentes. Um evento payment.succeeded indica que o pagamento foi processado; ele não informa se o cliente já tem o repositório GitHub ou o papel Discord. O evento delivered é a fonte da verdade para o cumprimento.
  • Mapeie revocation_reason para fluxos de retenção. Uma revogação subscription_on_hold geralmente significa que o cartão do cliente falhou e a próxima renovação reativará o acesso. Uma revogação manual ou subscription_cancelled é intencional. Trate-os de forma diferente na comunicação com o cliente.
  • Use a concessão id como sua chave de idempotência. Uma única concessão emite no máximo um evento created e no máximo um evento terminal (delivered ou failed), e no máximo um evento revoked. As re-entregas do sistema de webhook podem repetir eventos; deduplique na concessão id mais type.
  • Inspecione license_key e digital_product_delivery para 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_url ao cliente. O evento entitlement_grant.created para fluxos de assinantes do Discord, GitHub ou Notion inclui um oauth_url e oauth_expires_at. Envie por email ao cliente ou exiba em seu aplicativo para desbloquear a entrega.

Dicas de integração

  • Aguarde entitlement_grant.delivered antes de desbloquear funcionalidades dependentes. Um evento payment.succeeded informa 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 evento delivered é a fonte de verdade para o preenchimento.
  • Associe revocation_reason aos fluxos de retenção. Uma revogação subscription_on_hold geralmente significa que o cartão do cliente falhou e a próxima renovação concederá o acesso novamente. Uma revogação manual ou subscription_cancelled é intencional. Trate-as de forma diferente nas mensagens ao cliente.
  • Use id do grant como sua idempotency key. Um único grant emite no máximo um evento created, no máximo um evento terminal (delivered ou failed) e no máximo um evento revoked. As reentregas do sistema de webhook podem repetir eventos; elimine duplicatas usando id do grant junto com type.
  • Leia integration_type para reconhecer o tipo de grant. O payload contém integration_type diretamente (por exemplo, license_key, digital_files, discord). Os objetos aninhados license_key e digital_product_delivery são preenchidos quando seus respectivos grants são entregues; um grant de license key preenchido manualmente permanece Pending com integration_type: "license_key" e um null license_key até que você o preencha.
  • Para grants baseados em OAuth, mostre oauth_url ao cliente. O evento entitlement_grant.created para fluxos de assinantes do Discord, GitHub ou Notion inclui oauth_url e oauth_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
string
obrigatório

Brand id this grant belongs to.

business_id
string
obrigatório

Identifier of the business that owns the grant.

created_at
string<date-time>
obrigatório

Timestamp when the grant was created.

customer_id
string
obrigatório

Identifier of the customer the grant was issued to.

entitlement_id
string
obrigatório

Identifier of the entitlement this grant was issued from.

id
string
obrigatório

Unique identifier of the grant.

integration_type
enum<string>
obrigatório

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

Opções disponíveis:
discord,
telegram,
github,
figma,
framer,
notion,
digital_files,
license_key,
feature_flag
metadata
Metadata · object
obrigatório

Arbitrary key-value metadata recorded on the grant.

status
enum<string>
obrigatório

Lifecycle status of the grant.

Opções disponíveis:
Pending,
Delivered,
Failed,
Revoked
updated_at
string<date-time>
obrigatório

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 modificação em 21 de agosto de 2026