Rättighetsbeviljande
Den nyttolast som skickas till din webhook-endpoint när ett rättighetsbeviljande skapas, levereras, misslyckas eller återkallas.
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.EntitlementGrantResponse nyttolast dokumenterad i schemat nedan.
Händelsetriggare
entitlement_grant.created
En beviljanderad infogades just. Beviljandet har alltid en stabilid 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_urlsom kunden måste besöka för att slutföra medgivandet. Grant förblirPendingtills kunden auktoriserar. - Plattformsdirekta integrationer (Telegram, Framer, Digital Files) befinner sig endast kort i
Pendingmedan plattformsanropet körs och övergår sedan tillDelivered.
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).
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ältetrevocation_reason registrerar utlösaren.
Nyttolastvarianter
Fältetdata ä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_keyinkluderas närintegration_typeärlicense_keyoch en nyckel har utfärdats. Det innehåller den genererade nyckeln, utgångsdatumet och aktiveringsanvändningen. För en manuellt uppfylld grant som fortfarande ärPendingär det här objektetnulltills du uppfyller grant.digital_product_deliveryinkluderas närintegration_typeärdigital_files. Det innehåller försignerade nedladdnings-URL:er, den valfriainstructionsoch den valfriaexternal_url.featureinkluderas närintegration_typeärfeature_flag. Det innehållerfeature_typeochfeature_idför den kapacitet som grant ger.
null; den relevanta konfigurationen finns i själva entitlement, inte i grant.
Exempel på nyttolaster
Licensnyckel levererad (entitlement_grant.delivered)
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.deliveredinnan du låser upp beroende funktioner. Enpayment.succeededhä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_reasontill retention flöden. Ensubscription_on_holdåterkallelse innebär vanligtvis att kundens kort misslyckades och nästa förnyelse kommer att nybevilja åtkomst. Enmanualellersubscription_cancelledåterkallelse är avsiktlig. Behandla dem olika i kundmeddelandena. - Använd grant
idsom din idempotensnyckel. Ett enda beviljande avger högst ettcreated-händelse och högst en slutlig händelse (deliveredellerfailed), och högst ettrevoked-händelse. Återleveranser från webhooksystemet kan upprepa händelser; dupplikat på grantidplustype. - Inspektera
license_keyochdigital_product_deliveryfö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_urlför kunden.entitlement_grant.created-händelsen för Discord, GitHub, eller Notion prenumerantflöden inkluderar enoauth_urlochoauth_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.deliveredinnan du låser upp beroende funktioner. Enpayment.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_reasontill retention-flöden. Ettsubscription_on_hold-återkallande betyder vanligtvis att kundens kort nekades och att nästa förnyelse ger åtkomst igen. Ettmanual- ellersubscription_cancelled-återkallande är avsiktligt. Hantera dem olika i kundkommunikationen. - Använd grantens
idsom din idempotency key. En enda grant genererar högst encreated-händelse, högst en terminalhändelse (deliveredellerfailed) och högst enrevoked-händelse. Omleveranser från webhook-systemet kan upprepa händelser; deduplicera på grantensidsamttype. - Läs
integration_typeför att identifiera grant-typen. Payloaden innehållerintegration_typedirekt (till exempellicense_key,digital_files,discord). De nästlade objektenlicense_keyochdigital_product_deliveryfylls i när deras respektive grants har levererats; en manuellt uppfylld licensnyckel-grant förblirPendingmedintegration_type: "license_key"och ettnulllicense_keytills du uppfyller den. - Visa
oauth_urlför kunden vid OAuth-baserade grants.entitlement_grant.created-händelsen för prenumerantflöden i Discord, GitHub eller Notion innehåller enoauth_urlochoauth_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 this grant belongs to.
Identifier of the business that owns the grant.
Timestamp when the grant was created.
Identifier of the customer the grant was issued to.
Identifier of the entitlement this grant was issued from.
Unique identifier of the grant.
The integration type of the grant's entitlement (e.g. license_key).
discord, telegram, github, figma, framer, notion, digital_files, license_key, feature_flag Arbitrary key-value metadata recorded on the grant.
Lifecycle status of the grant.
Pending, Delivered, Failed, Revoked Timestamp when the grant was last modified.
Timestamp when the grant transitioned to delivered, when applicable.
Digital-product-delivery payload, present when the entitlement
integration is digital_files.
Machine-readable code reported when delivery failed, when applicable.
Human-readable message reported when delivery failed, when applicable.
Typed feature payload, present only when the entitlement integration is
feature_flag; null for every other integration type.
License-key delivery payload, present when the entitlement integration
is license_key.
Timestamp when oauth_url stops being valid, when applicable.
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.
Identifier of the payment that triggered this grant, when applicable.
Reason recorded when the grant was revoked, when applicable.
Timestamp when the grant transitioned to revoked, when applicable.
Identifier of the subscription that triggered this grant, when applicable.