Skip to main content

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. Alla fyra händelser delar samma EntitlementGrantResponse nyttolast dokumenterad i schemat nedan.

Händelsetriggare

entitlement_grant.created

En beviljanderad infogades just. Beviljandet har alltid en stabil id från och med nu, även om dess status ändras. Använd denna händelse för att registrera att uppfyllande pågår. För automatiskt uppfyllda licensnycklar infogas raden direkt med status: "Delivered" och delivered_at ifyllda, så en enda created-händelse följs inte av några ytterligare statusändringar om inte grant 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) innehåller en oauth_url som kunden måste besöka för att slutföra medgivandet. Grant förblir Pending tills kunden auktoriserar.
  • Plattformsdirekta integrationer (Telegram, Framer, Digital Files) befinner sig endast kort i Pending medan plattformsanropet körs och övergår 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. Grant övergick från Pending till Delivered. Kunden har nu den åtkomst som beskrivs av entitlement. Använd den här händelsen för att låsa upp beroende funktioner i dina egna system, till exempel för att skapa en workspace, skicka ett anpassat välkomstmeddelande eller markera en “fulfilled”-flagga. Payloadens delivered_at-fält anger när leveransen slutfördes. För grants som anlände med Delivered vid skapandet får du created- och delivered-händelser direkt efter varandra. 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.

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)

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.

Beviljande återkallat vid prenumerationsavslut (entitlement_grant.revoked)

Leverans misslyckades (entitlement_grant.failed)


  • Vänta på entitlement_grant.delivered innan du låser upp beroende funktioner. En payment.succeeded händelse talar om för dig att pengarna gått igenom; det talar inte om för dig att kunden har GitHub-repot eller Discord-rollen än. delivered-händelsen är den sanningskälla för uppfyllande.
  • Kartlägg revocation_reason till retention flöden. En subscription_on_hold återkallelse innebär vanligtvis att kundens kort misslyckades och nästa förnyelse kommer att nybevilja åtkomst. En manual eller subscription_cancelled återkallelse är avsiktlig. Behandla dem olika i kundmeddelandena.
  • Använd grant id som din idempotensnyckel. Ett enda beviljande avger högst ett created-händelse och högst en slutlig händelse (delivered eller failed), och högst ett revoked-händelse. Återleveranser från webhooksystemet kan upprepa händelser; dupplikat på grant id plus type.
  • Inspektera license_key och digital_product_delivery för att känna igen integrationstypen. Grant nyttolasten i sig bär inte integrationstypen, men exakt ett av dessa kapslade objekt fylls i för licensnyckel och digitala filer rättigheter.
  • För OAuth-baserade beviljanden, visa oauth_url för kunden. entitlement_grant.created-händelsen för Discord, GitHub, eller Notion prenumerantflöden inkluderar en oauth_url och oauth_expires_at. Maila det till kunden eller visa det i din app för att låsa upp leveransen.

Integreringstips

  • Vänta på entitlement_grant.delivered innan du låser upp beroende funktioner. En payment.succeeded-händelse visar att betalningen har gått igenom; den visar inte att kunden ännu har GitHub-repot eller Discord-rollen. delivered-händelsen är källan till sanningen för uppfyllelse.
  • Koppla revocation_reason till retention-flöden. Ett subscription_on_hold-återkallande betyder vanligtvis att kundens kort nekades och att nästa förnyelse ger åtkomst igen. Ett manual- eller subscription_cancelled-återkallande är avsiktligt. Hantera dem olika i kundkommunikationen.
  • Använd grantens id som din idempotency key. En enda grant genererar högst en created-händelse, högst en terminalhändelse (delivered eller failed) och högst en revoked-händelse. Omleveranser från webhook-systemet kan upprepa händelser; deduplicera på grantens id samt type.
  • Läs integration_type för att identifiera grant-typen. 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 grants har levererats; en manuellt uppfylld licensnyckel-grant förblir Pending med integration_type: "license_key" och ett null license_key tills du uppfyller den.
  • Visa oauth_url för kunden vid OAuth-baserade grants. entitlement_grant.created-händelsen för prenumerantflöden i Discord, GitHub eller Notion innehåller en oauth_url och oauth_expires_at. Skicka den via e-post till kunden eller visa den i din app för att slutfö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.

id
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.

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.

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.

Senast ändrad 21 augusti 2026