Concessão de Direitos

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.

Evento	Descrição
`entitlement_grant.created`	Uma nova linha de grant foi criada. O status é `Delivered` imediatamente para license keys preenchidas automaticamente e feature flags, e `Pending` para license keys preenchidas manualmente e todas as outras integrações.
`entitlement_grant.delivered`	O grant muda para delivered. O cliente agora tem acesso à plataforma, ao arquivo ou à license key incluídos no entitlement.
`entitlement_grant.failed`	A entrega falhou e não será repetida. Inspecione `error_code` e `error_message`.
`entitlement_grant.revoked`	O acesso foi revogado. Inspecione `revocation_reason` para entender o motivo.

Todos os quatro eventos compartilham a mesma carga útil EntitlementGrantResponse documentada no esquema abaixo.

Desencadeadores de Eventos

entitlement_grant.created

Uma linha de grant foi inserida. A partir desse momento, o grant sempre tem um id estável, mesmo que seu status mude. Use esse evento para registrar que o fulfillment está em andamento. Para license keys preenchidas automaticamente e feature flags, a linha é inserida diretamente com status: "Delivered" e delivered_at preenchidos, portanto um único evento created é seguido por nenhuma outra mudança 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) usam um oauth_url que o cliente deve visitar para concluir o consentimento. Dodo Payments tenta criá-lo quando a concessão é criada, então entitlement_grant.created pode incluí-lo; se estiver null, ele será preenchido quando o cliente iniciar o fluxo de aceitação no Customer Portal. A concessão 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 mudou para Delivered, geralmente a partir de Pending. O cliente agora tem o acesso descrito pelo entitlement. Use esse evento para desbloquear recursos dependentes em seus próprios sistemas, por exemplo, para provisionar um workspace, enviar um e-mail de boas-vindas personalizado ou marcar uma flag como “fulfilled”. O campo delivered_at do payload registra quando a entrega foi concluída. delivered é disparado sempre que o status de um grant existente muda para Delivered: a partir de Pending, quando um grant OAuth com falha é posteriormente bem-sucedido ou quando um grant revogado é restaurado. Um grant que chega como Delivered na criação, como uma license key preenchida automaticamente, dispara apenas created. 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.

`revocation_reason`	Disparador
`subscription_cancelled`	A assinatura do cliente foi cancelada (evento `subscription.cancelled`).
`subscription_on_hold`	A assinatura está em espera devido a falha na renovação (`subscription.on_hold`). Recuperável: uma tentativa bem-sucedida produz uma nova concessão.
`subscription_expired`	A assinatura chegou ao fim do seu termo (`subscription.expired`).
`plan_changed`	O plano mudou; concessões antigas são revogadas antes de novas serem emitidas (`subscription.plan_changed`).
`refund`	Um reembolso foi processado para o pagamento único original (`refund.succeeded`).
`manual`	Um comerciante revogou a concessão via API ou painel. Revogações manuais não são automaticamente reativadas na renovação da assinatura.
`license_key_disabled`	A chave de licença por trás de uma concessão de chave de licença foi desativada. A concessão é reativada automaticamente se a chave for reativada.
`platform_external`	O lado da plataforma de uma integração saiu de sincronia (por exemplo, um papel do Discord foi removido manualmente, o aplicativo do GitHub perdeu acesso ao repositório, ou uma verificação de reconciliação detectou um alvo ausente). A concessão não é automaticamente reativada na renovação da assinatura até que o problema subjacente da plataforma seja resolvido.

`revocation_reason`	Gatilho
`subscription_cancelled`	A assinatura do cliente foi cancelada (evento `subscription.cancelled`).
`subscription_on_hold`	A assinatura está em espera devido à falha na renovação (`subscription.on_hold`). Recuperável: uma nova tentativa bem-sucedida gera uma nova concessão.
`subscription_paused`	A assinatura foi pausada (`subscription.paused`). Recuperável: retomar a assinatura gera uma nova concessão.
`subscription_expired`	A assinatura chegou ao fim do período contratado (`subscription.expired`).
`plan_changed`	O plano foi alterado; as concessões antigas são revogadas antes que novas sejam emitidas (`subscription.plan_changed`).
`refund`	Um reembolso foi processado para o pagamento único original (`refund.succeeded`).
`manual`	Um comerciante revogou a concessão por meio da API ou do painel. As revogações manuais não geram concessões novamente de forma automática na renovação da assinatura.
`license_key_disabled`	A chave de licença associada a uma concessão de chave de licença foi desativada. A concessão é reativada automaticamente se a chave for reativada.
`platform_external`	O lado da plataforma de uma integração ficou fora de sincronia (por exemplo, uma função do Discord foi removida manualmente, o GitHub App perdeu acesso ao repositório ou uma passagem de reconciliação detectou um destino ausente). A concessão não é gerada novamente de forma automática na renovação da assinatura até que o problema subjacente da plataforma seja resolvido.

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`)

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

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.

{
  "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"
  }
}

Arquivos Digitais Entregues (`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"
  }
}

Role do Discord Criada e Pendente (`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 Revogado no Cancelamento da Subscription (`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"
  }
}

Falha na Entrega (`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"
  }
}

Dicas de integração

Desbloqueie recursos dependentes quando uma concessão chegar a Delivered. 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. Trate entitlement_grant.delivered e também entitlement_grant.created com status: "Delivered", pois uma concessão entregue no momento da criação não dispara nenhum evento delivered.
Associe revocation_reason aos fluxos de retenção. Um cancelamento subscription_on_hold geralmente significa que o cartão do cliente falhou e que a próxima renovação concederá o acesso novamente. Um cancelamento manual ou subscription_cancelled é intencional. Trate-os de forma diferente nas mensagens ao cliente.
Detecte duplicatas com o cabeçalho webhook-id, não com o id da concessão. Uma concessão emite created uma vez, mas delivered e revoked podem ser disparados mais de uma vez, pois uma concessão cancelada pode ser restaurada e cancelada novamente. failed também nem sempre é final: uma concessão OAuth com falha ainda pode ser entregue. As reentregas do sistema de webhooks também podem repetir um evento. Ignore as repetições usando webhook-id e use o id da concessão como chave para seus próprios registros de concessão.
Leia integration_type para reconhecer o tipo de concessão. 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 suas respectivas concessões são entregues; uma concessão de chave de licença cumprida manualmente permanece Pending com integration_type: "license_key" e um null license_key até que você a cumpra.
Para concessões baseadas em OAuth, mostre oauth_url ao cliente. O evento entitlement_grant.created dos fluxos de assinantes do Discord, GitHub ou Notion pode incluir um oauth_url e oauth_expires_at. Se estiver null, aguarde um evento posterior ou direcione o cliente ao Customer Portal. Envie a URL por e-mail ao cliente ou exiba-a no seu aplicativo 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.

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.

Show child attributes

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.

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 Concessão de Direitos

Desencadeadores de Eventos

entitlement_grant.created

entitlement_grant.revoked

Variantes de Carga Útil

Exemplos de Carga Útil

Chave de licença entregue (`entitlement_grant.delivered`)

License Key Entregue (`entitlement_grant.delivered`)

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

Arquivos Digitais Entregues (`entitlement_grant.delivered`)

Role do Discord Criada e Pendente (`entitlement_grant.created`)

Grant Revogado no Cancelamento da Subscription (`entitlement_grant.revoked`)

Falha na Entrega (`entitlement_grant.failed`)

Dicas de integração

​Eventos de Webhook para Concessão de Direitos

​Desencadeadores de Eventos

​entitlement_grant.created

​entitlement_grant.revoked

​Variantes de Carga Útil

​Exemplos de Carga Útil

​Chave de licença entregue (entitlement_grant.delivered)

​License Key Entregue (entitlement_grant.delivered)

​License Key Aguardando Fulfillment Manual (entitlement_grant.created)

​Arquivos Digitais Entregues (entitlement_grant.delivered)

​Role do Discord Criada e Pendente (entitlement_grant.created)

​Grant Revogado no Cancelamento da Subscription (entitlement_grant.revoked)

​Falha na Entrega (entitlement_grant.failed)

​Dicas de integração

Eventos de Webhook para Concessão de Direitos

Desencadeadores de Eventos

entitlement_grant.created

entitlement_grant.revoked

Variantes de Carga Útil

Exemplos de Carga Útil

Chave de licença entregue (`entitlement_grant.delivered`)

License Key Entregue (`entitlement_grant.delivered`)

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

Arquivos Digitais Entregues (`entitlement_grant.delivered`)

Role do Discord Criada e Pendente (`entitlement_grant.created`)

Grant Revogado no Cancelamento da Subscription (`entitlement_grant.revoked`)

Falha na Entrega (`entitlement_grant.failed`)

Dicas de integração