Webhook Payloads

प्राधिकार अनुदान

जब प्राधिकार अनुदान बनाए जाते हैं, वितरित होते हैं, असफल होते हैं, या निरस्त होते हैं, तो आपके वेबहुक अंत बिंदु पर भेजा जाने वाला पेलोड।

प्राधिकार अनुदान वेबहुक घटनाएँ

जब भी किसी ग्राहक का प्राधिकार अनुदान स्थिति बदलता है, उदाहरण के लिए जब एक लाइसेंस कुंजी उत्पन्न होती है, एक Discord भूमिका आवंटित होती है, एक डाउनलोड लिंक प्रदान किया जाता है, या पहुंच निरस्त होती है, तो ये घटनाएँ चलती हैं। इन घटनाओं की सदस्यता लें ताकि आपका एप्लिकेशन इस बात के साथ तालमेल में रहे कि प्रत्येक ग्राहक को क्या पहुंच सकता है।

Event	विवरण
`entitlement_grant.created`	एक नई grant row बनाई गई। auto-fulfilled license keys और feature flags के लिए Status तुरंत `Delivered` होता है, और manually-fulfilled license keys तथा हर अन्य integration के लिए `Pending` होता है।
`entitlement_grant.delivered`	grant, delivered में परिवर्तित हो जाती है। अब customer के पास entitled platform, file या license key का access है।
`entitlement_grant.failed`	Delivery विफल रही और इसे दोबारा retry नहीं किया जा रहा है। `error_code` और `error_message` का निरीक्षण करें।
`entitlement_grant.revoked`	Access वापस ले लिया गया। कारण समझने के लिए `revocation_reason` का निरीक्षण करें।

सभी चार घटनाएँ नीचे दी गई स्कीमा में प्रलेखित समान EntitlementGrantResponse पेलोड साझा करती हैं।

घटना ट्रिगर

entitlement_grant.created

एक grant row insert की गई। इस बिंदु के बाद grant में हमेशा एक स्थिर id होता है, भले ही इसका status बदल जाए। Fulfillment की प्रक्रिया जारी है, यह रिकॉर्ड करने के लिए इस event का उपयोग करें। auto-fulfilled license keys और feature flags के लिए row सीधे status: "Delivered" और delivered_at को populated करके insert की जाती है, इसलिए एकल created event के बाद कोई और state change नहीं होता, जब तक कि grant को बाद में revoke न किया जाए। manually-fulfilled license keys (fulfillment_mode: manual वाली entitlements) के लिए row status: "Pending" के साथ आती है और इसमें कोई license_key object नहीं होता — अभी कोई key उपलब्ध नहीं है। यह event आपका संकेत है कि एक key fulfillment की प्रतीक्षा कर रही है; इसे POST /grants/{grant_id}/license-key के माध्यम से supply करें, जिसके बाद entitlement_grant.delivered fire होता है। Manual Fulfillment देखें। हर दूसरे integration के लिए row status: "Pending" के साथ आती है। Delivery पूरी होने के बाद delivered या failed event आता है:

OAuth-आधारित integrations (Discord, GitHub, Notion) एक oauth_url का उपयोग करते हैं, जिसे consent पूरा करने के लिए customer को खोलना होता है। Dodo Payments grant बनने पर इसे बनाने का प्रयास करता है, इसलिए entitlement_grant.created में यह शामिल हो सकता है; यदि यह null है, तो customer के Customer Portal से accept flow शुरू करने पर इसे भरा जाता है। Customer द्वारा authorize किए जाने तक grant Pending रहता है।
Platform-direct integrations (Telegram, Framer, Digital Files) केवल थोड़े समय के लिए Pending में रहते हैं, जब तक platform call चलती है, फिर Delivered में चले जाते हैं।

entitlement_grant.delivered

grant, सामान्यतः Pending से Delivered में परिवर्तित हुई। अब customer के पास entitlement में वर्णित access है। अपने systems में dependent features को unlock करने के लिए इस event का उपयोग करें, जैसे workspace provision करना, custom welcome email भेजना या “fulfilled” flag को mark करना। payload का delivered_at field यह दर्ज करता है कि delivery कब पूरी हुई। जब भी किसी मौजूदा grant का status बदलकर Delivered होता है, तब delivered fire होता है: Pending से, जब विफल OAuth grant बाद में सफल हो जाती है, या जब revoked grant restore की जाती है। Creation के समय ही Delivered status वाली grant, जैसे auto-fulfilled license key, केवल created fire करती है।

entitlement_grant.failed

डिलीवरी का प्रयास किया गया और यह एक गैर-पुनः प्रयोज्य त्रुटि के साथ विफल रही। error_code और error_message फील्ड्स विफलता की व्याख्या करते हैं। सामान्य कारणों में एक रद्द किया हुआ OAuth टोकन, एक अस्वीकार की गई प्लेटफॉर्म अनुमति, या एक गायब लक्ष्य (जैसे, एक हटाया गया Discord गिल्ड) शामिल है।

entitlement_grant.failed को कार्यात्मक माना जाता है। ग्राहक ने भुगतान किया लेकिन उसे एक्सेस नहीं मिला। अपनी समर्थन टीम को विफलताएँ बताएं या एक बार मूल समस्या हल हो जाने पर फिर से ग्रांट ट्रिगर करें।

entitlement_grant.revoked

प्लेटफ़ॉर्म स्तर पर एक्सेस हटा दी गई: Discord भूमिका हटा दी गई, GitHub कोलैबोरेटर हटा दिया गया, लाइसेंस की अक्षम कर दी गई, फाइल डाउनलोड URLs अब जारी नहीं की गईं। revocation_reason फील्ड ट्रिगर रिकॉर्ड करता है।

`revocation_reason`	ट्रिगर
`subscription_cancelled`	ग्राहक का subscription रद्द कर दिया गया (`subscription.cancelled` event)।
`subscription_on_hold`	विफल renewal के कारण subscription hold पर है (`subscription.on_hold`)। Recoverable: सफल retry से re-grant होता है।
`subscription_paused`	subscription pause कर दिया गया (`subscription.paused`)। Recoverable: resume करने से re-grant होता है।
`subscription_expired`	subscription अपनी अवधि के अंत तक पहुँच गया (`subscription.expired`)।
`plan_changed`	plan बदल गया; नए grants जारी करने से पहले पुराने grants revoke कर दिए जाते हैं (`subscription.plan_changed`)।
`refund`	मूल one-time payment के लिए refund process किया गया (`refund.succeeded`)।
`manual`	किसी merchant ने API या dashboard के माध्यम से grant revoke किया। subscription renewal पर manual revokes का अपने-आप re-grant नहीं किया जाता।
`license_key_disabled`	license-key grant के पीछे license key disabled कर दी गई। key को फिर से enable करने पर grant अपने-आप re-activate हो जाता है।
`platform_external`	integration का platform side sync से बाहर हो गया (उदाहरण के लिए, Discord role को manually हटा दिया गया, GitHub App ने repository access खो दिया, या reconciliation pass ने कोई missing target detect किया)। underlying platform issue का समाधान होने तक subscription renewal पर grant का अपने-आप re-grant नहीं किया जाता।

पेलोड वेरिएंट्स

data field हमेशा एक EntitlementGrantResponse object होता है। Payload में एक integration_type field होता है (उदाहरण के लिए license_key, digital_files, discord), ताकि आप grant type को सीधे पहचान सकें। तीन integration types अतिरिक्त nested objects भी attach करते हैं:

license_key तब शामिल होता है जब integration_type, license_key हो और एक key जारी की गई हो। इसमें generated key, expiry और activation usage शामिल होते हैं। अभी भी Pending में मौजूद manually-fulfilled grant के लिए यह object null होता है, जब तक कि आप grant fulfill न कर दें।
digital_product_delivery तब शामिल होता है जब integration_type, digital_files हो। इसमें presigned download URLs, optional instructions और optional external_url शामिल होते हैं।
feature तब शामिल होता है जब integration_type, feature_flag हो। इसमें grant द्वारा प्रदान की गई capability का feature_type और feature_id शामिल होता है।

अन्य सभी integration types (Discord, GitHub, Telegram, Figma, Framer, Notion) के लिए ये nested fields null होते हैं; संबंधित configuration entitlement में capture की जाती है, grant में नहीं।

सैंपल पेलोड्स

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

यह तब fire होता है जब कोई customer ऐसा product खरीदता है जिसकी License Key entitlement में fulfillment_mode: manual का उपयोग किया गया हो। grant Pending होती है और इसमें अभी कोई license_key object नहीं होता — merchant को key supply करनी होगी।

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

Digital Files Delivered (`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 Role Created and Pending (`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 Revoked on Subscription Cancellation (`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"
  }
}

Delivery Failed (`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"
  }
}

इंटीग्रेशन टिप्स

जब कोई grant Delivered तक पहुँच जाए, तो उस पर निर्भर features को unlock करें। एक payment.succeeded event आपको बताता है कि payment clear हो गया है; यह नहीं बताता कि customer के पास अभी GitHub repo या Discord role है। entitlement_grant.delivered को handle करें, और साथ ही entitlement_grant.created को status: "Delivered" के साथ handle करें, क्योंकि creation पर deliver होने वाला grant कोई delivered event नहीं भेजता।
revocation_reason को retention flows से map करें। subscription_on_hold revoke का आमतौर पर अर्थ है कि customer का card fail हो गया है और अगला renewal access को फिर से grant करेगा। manual या subscription_cancelled revoke जानबूझकर किया गया है। Customer messaging में इनके साथ अलग-अलग व्यवहार करें।
Grant id के बजाय webhook-id header से duplicates का पता लगाएँ। एक grant created केवल एक बार emit करता है, लेकिन delivered और revoked में से प्रत्येक एक से अधिक बार fire हो सकता है, क्योंकि revoked grant को restore करके फिर से revoke किया जा सकता है। failed भी हमेशा अंतिम नहीं होता: failed OAuth grant को फिर भी deliver किया जा सकता है। Webhook system से होने वाली re-deliveries भी किसी event को दोहरा सकती हैं। webhook-id के आधार पर repeats को skip करें, और अपने grant records की key grant id पर रखें।
Grant type पहचानने के लिए integration_type पढ़ें। Payload में integration_type सीधे मौजूद होता है (उदाहरण के लिए license_key, digital_files, discord)। license_key और digital_product_delivery nested objects अपने-अपने grants deliver होने के बाद populate होते हैं; manually-fulfilled license-key grant Pending ही रहता है, जिसमें integration_type: "license_key" और एक null license_key होता है, जब तक आप उसे fulfill नहीं करते।
OAuth-आधारित grants के लिए oauth_url customer को दिखाएँ। Discord, GitHub या Notion subscriber flows के लिए entitlement_grant.created event में oauth_url और oauth_expires_at शामिल हो सकते हैं। यदि यह null है, तो बाद के event की प्रतीक्षा करें या customer को Customer Portal पर भेजें। Delivery को unblock करने के लिए URL customer को email करें या उसे अपने app में दिखाएँ।

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

brand_id

string

आवश्यक

Brand id this grant belongs to.

business_id

string

आवश्यक

Identifier of the business that owns the grant.

created_at

string<date-time>

आवश्यक

Timestamp when the grant was created.

customer_id

string

आवश्यक

Identifier of the customer the grant was issued to.

entitlement_id

string

आवश्यक

Identifier of the entitlement this grant was issued from.

string

आवश्यक

Unique identifier of the grant.

integration_type

enum<string>

आवश्यक

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

उपलब्ध विकल्प:

discord,

telegram,

github,

figma,

framer,

notion,

digital_files,

license_key,

feature_flag

metadata

Metadata · object

आवश्यक

Arbitrary key-value metadata recorded on the grant.

Show child attributes

status

enum<string>

आवश्यक

Lifecycle status of the grant.

उपलब्ध विकल्प:

Pending,

Delivered,

Failed,

Revoked

updated_at

string<date-time>

आवश्यक

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.

अंतिम संशोधन 26 सितंबर 2026

{
  "brand_id": "<string>",
  "business_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "entitlement_id": "<string>",
  "id": "<string>",
  "metadata": {},
  "updated_at": "2023-11-07T05:31:56Z",
  "delivered_at": "2023-11-07T05:31:56Z",
  "digital_product_delivery": {
    "files": [
      {
        "download_url": "<string>",
        "expires_in": 123,
        "file_id": "<string>",
        "filename": "<string>",
        "content_type": "<string>",
        "file_size": 123
      }
    ],
    "external_url": "<string>",
    "instructions": "<string>"
  },
  "error_code": "<string>",
  "error_message": "<string>",
  "feature": {
    "feature_id": "<string>",
    "feature_type": "boolean"
  },
  "license_key": {
    "activations_used": 123,
    "id": "<string>",
    "key": "<string>",
    "activations_limit": 123,
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "oauth_expires_at": "2023-11-07T05:31:56Z",
  "oauth_url": "<string>",
  "payment_id": "<string>",
  "revocation_reason": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "subscription_id": "<string>"
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

प्राधिकार अनुदान