Rättighetsbeviljande

Webhook-händelser för rättighetsbeviljande

Dessa händelser utlöses när en kunds rättighetsbeviljande ändrar tillstånd, till exempel när en licensnyckel genereras, en Discord-roll tilldelas, en nedladdningslänk tillhandahålls eller åtkomst återkallas. Prenumerera på dessa händelser för att hålla din applikation synkroniserad med vad varje kund kan komma åt.

Händelse	Beskrivning
`entitlement_grant.created`	En ny rad för beviljande skapades. Statusen är `Delivered` direkt för automatiskt uppfyllda licensnycklar och feature flags, och `Pending` för manuellt uppfyllda licensnycklar och alla andra integrationer.
`entitlement_grant.delivered`	Beviljandet övergår till levererat. Kunden har nu åtkomst till den berättigade plattformen, filen eller licensnyckeln.
`entitlement_grant.failed`	Leveransen misslyckades och försöks inte igen. Granska `error_code` och `error_message`.
`entitlement_grant.revoked`	Åtkomsten drogs in. Granska `revocation_reason` för att förstå varför.

Alla fyra händelser delar samma EntitlementGrantResponse nyttolast dokumenterad i schemat nedan.

Händelsetriggare

entitlement_grant.created

En rad för beviljande infogades. Beviljandet har alltid ett stabilt id från och med nu, även om dess status ändras. Använd den här händelsen för att registrera att uppfyllelsen pågår. För automatiskt uppfyllda licensnycklar och feature flags infogas raden direkt med status: "Delivered" och delivered_at ifyllda, så att en enda created-händelse följs av inga ytterligare statusändringar, såvida beviljandet inte senare återkallas. För manuellt uppfyllda licensnycklar (entitlements med fulfillment_mode: manual) kommer raden med status: "Pending" och utan något license_key-objekt — det finns ännu ingen nyckel. Den här händelsen signalerar att en nyckel väntar på att uppfyllas; leverera den via POST /grants/{grant_id}/license-key, vilket sedan utlöser entitlement_grant.delivered. Se Manuell uppfyllelse. För alla andra integrationer kommer raden med status: "Pending". En delivered- eller failed-händelse följer när leveransen har slutförts:

OAuth-baserade integrationer (Discord, GitHub, Notion) använder en oauth_url som kunden måste besöka för att slutföra medgivandet. Dodo Payments försöker skapa den när grantet skapas, så entitlement_grant.created kan innehålla den. Om den är null fylls den i när kunden startar acceptflödet från Customer Portal. Grantet förblir Pending tills kunden har auktoriserat.
Plattformsdirekta integrationer (Telegram, Framer, Digital Files) förblir Pending endast kortvarigt medan plattformsanropet körs och flyttas sedan till Delivered.

Beviljandet övergick från pending till delivered. Kunden har nu åtkomsten som beskrivs av rättigheterna. Använd denna händelse för att låsa upp beroende funktioner i dina egna system, till exempel för att tillhandahålla en arbetsyta, skicka ett anpassat välkomstmail eller markera en “uppfylld” flagga. Beviljandet övergick till Delivered, vanligtvis från Pending. Kunden har nu den åtkomst som beskrivs av berättigandet. Använd den här händelsen för att låsa upp beroende funktioner i dina egna system, till exempel genom att provisionera en arbetsyta, skicka ett anpassat välkomstmeddelande eller markera en “fulfilled”-flagga. Fältet delivered_at i payloaden anger när leveransen slutfördes. delivered utlöses varje gång statusen för ett befintligt beviljande ändras till Delivered: från Pending, när ett misslyckat OAuth-beviljande senare lyckas eller när ett återkallat beviljande återställs. Ett beviljande som anländer som Delivered vid skapandet, till exempel en automatiskt uppfylld licensnyckel, utlöser endast created. Leverans försöktes och misslyckades med ett icke-återprovbart fel. Fälten error_code och error_message förklarar felet. Vanliga orsaker inkluderar en återkallad OAuth-token, en nekad plattformsbehörighet eller ett saknat mål (t.ex., en raderad Discord-gille).

Behandla entitlement_grant.failed som åtgärdsbar. Kunden betalade men fick inte åtkomst. Framhäv misslyckanden för din supportteam eller utlös en ombeviljning när den underliggande frågan är löst.

entitlement_grant.revoked

Åtkomst drogs tillbaka på plattformsnivån: Discord-roll borttagen, GitHub-samarbetare borttagen, licensnyckel inaktiverad, filnedladdnings-URL:er ej längre tillhandahållna. Fältet revocation_reason registrerar utlösaren.

`revocation_reason`	Utlösare
`subscription_cancelled`	Kundens prenumeration avbröts (`subscription.cancelled` händelse).
`subscription_on_hold`	Prenumerationen är på paus på grund av misslyckad förnyelse (`subscription.on_hold`). Återhämtbar: En lyckad omprovning leder till en ombeviljning.
`subscription_expired`	Prenumerationen nådde slutet av dess period (`subscription.expired`).
`plan_changed`	Planen ändrades; gamla beviljanden återkallas innan nya utfärdas (`subscription.plan_changed`).
`refund`	En återbetalning behandlades för den ursprungliga engångsbetalningen (`refund.succeeded`).
`manual`	En handlare återkallade beviljandet via API eller instrumentpanelen. Manuella återkallelser återbeviljas inte automatiskt vid prenumerationsförnyelser.
`license_key_disabled`	Licensnyckeln bakom en licensnyckel-beviljande inaktiverades. Beviljandet återaktiveras automatiskt om nyckeln återaktiveras.
`platform_external`	Plattformsidan av en integration gick ur synk (till exempel, en Discord-roll togs bort manuellt, GitHub-appen förlorade repository-åtkomst, eller en avstämningspass upptäckte ett saknat mål). Beviljandet återbeviljas inte automatiskt vid prenumerationsförnyelser förrän den underliggande plattformsfrågan är löst.

`revocation_reason`	Utlösare
`subscription_cancelled`	Kundens prenumeration avslutades (`subscription.cancelled`-händelse).
`subscription_on_hold`	Prenumerationen är pausad på grund av en misslyckad förnyelse (`subscription.on_hold`). Kan återställas: ett lyckat nytt försök skapar en ny tilldelning.
`subscription_paused`	Prenumerationen pausades (`subscription.paused`). Kan återställas: återupptagning skapar en ny tilldelning.
`subscription_expired`	Prenumerationen nådde slutet av sin löptid (`subscription.expired`).
`plan_changed`	Planen ändrades; gamla tilldelningar återkallas innan nya utfärdas (`subscription.plan_changed`).
`refund`	En återbetalning behandlades för den ursprungliga engångsbetalningen (`refund.succeeded`).
`manual`	En handlare återkallade tilldelningen via API:t eller instrumentpanelen. Manuella återkallanden tilldelas inte automatiskt på nytt vid förnyelse av prenumerationen.
`license_key_disabled`	Licensnyckeln bakom en licensnyckeltilldelning inaktiverades. Tilldelningen aktiveras automatiskt igen om nyckeln återaktiveras.
`platform_external`	Plattformssidan av en integration hamnade ur synk (till exempel togs en Discord-roll bort manuellt, GitHub App förlorade åtkomst till ett arkiv eller en avstämning upptäckte ett saknat mål). Tilldelningen tilldelas inte automatiskt på nytt vid förnyelse av prenumerationen förrän det underliggande plattformsproblemet har lösts.

Nyttolastvarianter

Fältet data är alltid ett EntitlementGrantResponse-objekt. Två integrationstyper bifogar extra kapslade objekt: Fältet data är alltid ett EntitlementGrantResponse-objekt. Payloaden innehåller ett integration_type-fält (till exempel license_key, digital_files, discord), så att du kan identifiera grant-typen direkt. Tre integrationstyper innehåller dessutom extra nästlade objekt:

license_key inkluderas när integration_type är license_key och en nyckel har utfärdats. Det innehåller den genererade nyckeln, utgångsdatumet och aktiveringsanvändningen. För en manuellt uppfylld grant som fortfarande är Pending är det här objektet null tills du uppfyller grant.
digital_product_delivery inkluderas när integration_type är digital_files. Det innehåller försignerade nedladdnings-URL:er, den valfria instructions och den valfria external_url.
feature inkluderas när integration_type är feature_flag. Det innehåller feature_type och feature_id för den kapacitet som grant ger.

För alla andra integrationstyper (Discord, GitHub, Telegram, Figma, Framer, Notion) är dessa nästlade fält null; den relevanta konfigurationen finns i själva entitlement, inte i grant.

Exempel på nyttolaster

Licensnyckel levererad (`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"
  }
}

Licensnyckel väntar på manuell uppfyllelse (`entitlement_grant.created`)

Utlöses när en kund köper en produkt vars License Key-entitlement använder fulfillment_mode: manual. Grant är Pending utan något license_key-objekt ännu — merchant måste tillhandahålla nyckeln.

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

Digitala filer levererade (`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"
  }
}

Discord-roll skapad och väntande (`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"
  }
}

Beviljande återkallat vid avslutad prenumeration (`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"
  }
}

Leveransen misslyckades (`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"
  }
}

Integreringstips

Lås upp beroende funktioner när ett grant når Delivered. En payment.succeeded-händelse talar om för dig att pengarna har gått igenom; den talar inte om att kunden redan har GitHub-repot eller Discord-rollen. Hantera entitlement_grant.delivered, och även entitlement_grant.created med status: "Delivered", eftersom ett grant som levereras när det skapas inte utlöser någon delivered-händelse.
Koppla revocation_reason till retentionflöden. Ett subscription_on_hold revoke innebär vanligtvis att kundens kort misslyckades och att nästa förnyelse kommer att bevilja åtkomsten igen. Ett manual- eller subscription_cancelled revoke är avsiktligt. Hantera dem olika i kundkommunikationen.
Identifiera dubbletter med webhook-id-headern, inte grantets id. Ett grant skickar created en gång, men delivered och revoked kan var och en utlösas flera gånger, eftersom ett återkallat grant kan återställas och återkallas igen. failed är inte heller alltid slutgiltigt: ett misslyckat OAuth-grant kan fortfarande levereras. Oleveranser från webhook-systemet kan också upprepa en händelse. Hoppa över upprepningar baserat på webhook-id och använd grantets id som nyckel för dina egna grant-poster.
Läs integration_type för att identifiera granttypen. Payloaden innehåller integration_type direkt (till exempel license_key, digital_files, discord). De nästlade objekten license_key och digital_product_delivery fylls i när deras respektive grant har levererats. Ett manuellt uppfyllt license-key-grant förblir Pending med integration_type: "license_key" och ett null license_key tills du uppfyller det.
För OAuth-baserade grant ska du visa oauth_url för kunden. entitlement_grant.created-händelsen för prenumerantflöden i Discord, GitHub eller Notion kan innehålla en oauth_url och oauth_expires_at. Om den är null väntar du på en senare händelse eller hänvisar kunden till Customer Portal. Skicka URL:en till kunden via e-post eller visa den i din app för att möjliggöra leveransen.

Detailed view of a single entitlement grant: who it's for, its lifecycle state, and any integration-specific delivery payload.

brand_id

string

obligatorisk

Brand id this grant belongs to.

business_id

string

obligatorisk

Identifier of the business that owns the grant.

created_at

string<date-time>

obligatorisk

Timestamp when the grant was created.

customer_id

string

obligatorisk

Identifier of the customer the grant was issued to.

entitlement_id

string

obligatorisk

Identifier of the entitlement this grant was issued from.

string

obligatorisk

Unique identifier of the grant.

integration_type

enum<string>

obligatorisk

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

Tillgängliga alternativ:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

obligatorisk

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

obligatorisk

Lifecycle status of the grant.

Tillgängliga alternativ:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

obligatorisk

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

Webhook-händelser för rättighetsbeviljande

Händelsetriggare

entitlement_grant.created

entitlement_grant.revoked

Nyttolastvarianter

Exempel på nyttolaster

Licensnyckel levererad (`entitlement_grant.delivered`)

Licensnyckel levererad (`entitlement_grant.delivered`)

Licensnyckel väntar på manuell uppfyllelse (`entitlement_grant.created`)

Digitala filer levererade (`entitlement_grant.delivered`)

Discord-roll skapad och väntande (`entitlement_grant.created`)

Beviljande återkallat vid avslutad prenumeration (`entitlement_grant.revoked`)

Leveransen misslyckades (`entitlement_grant.failed`)

Integreringstips

​Webhook-händelser för rättighetsbeviljande

​Händelsetriggare

​entitlement_grant.created

​entitlement_grant.revoked

​Nyttolastvarianter

​Exempel på nyttolaster

​Licensnyckel levererad (entitlement_grant.delivered)

​Licensnyckel levererad (entitlement_grant.delivered)

​Licensnyckel väntar på manuell uppfyllelse (entitlement_grant.created)

​Digitala filer levererade (entitlement_grant.delivered)

​Discord-roll skapad och väntande (entitlement_grant.created)

​Beviljande återkallat vid avslutad prenumeration (entitlement_grant.revoked)

​Leveransen misslyckades (entitlement_grant.failed)

​Integreringstips

Webhook-händelser för rättighetsbeviljande

Händelsetriggare

entitlement_grant.created

entitlement_grant.revoked

Nyttolastvarianter

Exempel på nyttolaster

Licensnyckel levererad (`entitlement_grant.delivered`)

Licensnyckel levererad (`entitlement_grant.delivered`)

Licensnyckel väntar på manuell uppfyllelse (`entitlement_grant.created`)

Digitala filer levererade (`entitlement_grant.delivered`)

Discord-roll skapad och väntande (`entitlement_grant.created`)

Beviljande återkallat vid avslutad prenumeration (`entitlement_grant.revoked`)

Leveransen misslyckades (`entitlement_grant.failed`)

Integreringstips