Canonical runtime architecture
The event model in Licenzy is intentionally layered. Stripe is the billing signal, Licenzy entitlements are the runtime source of truth, access APIs answer runtime decisions, and outbound webhooks propagate resulting runtime state to your own systems.
- Stripe delivers billing events to Licenzy through the tenant webhook.
- Licenzy processes those events into entitlement state.
- Your backend reads that state through runtime access and entitlement endpoints.
- Licenzy can also emit outbound events to keep your own systems in sync.
Trust boundary
Payment collection is not the runtime decision. The runtime decision comes from webhook-processed entitlement state, not from a browser redirect or Stripe object you inspect directly in your app.
Golden path runtime flow
This is the primary lifecycle to keep in mind when integrating Licenzy with your own backend:
- Stripe Checkout is created through Licenzy.
- Stripe later delivers the tenant webhook event to Licenzy.
- Licenzy updates entitlement state.
- Runtime access becomes available through access and entitlement reads.
- Licenzy emits the matching outbound runtime event.
- Your backend uses that outbound event to update local caches, analytics, or secondary systems.
Mental model
Stripe delivery changes Licenzy runtime state first. Outbound Licenzy events come after that runtime state exists and should be treated as propagation, not as the original billing signal.
Inbound and outbound responsibilities are different
Stripe inbound delivery and Licenzy outbound delivery solve different problems and should not be treated as the same event stream.
- Inbound Stripe lifecycle explains how billing signals enter Licenzy.
- Runtime state propagation explains how entitlements become access and customer-visible state.
- Outbound Licenzy webhooks explain how Licenzy publishes runtime changes back to your systems.
- Support and operational investigation explains how operators inspect delivery history and recover state from the portal.
Event architecture map
- Inbound Stripe lifecycle for tenant webhook setup, retries, and processing boundaries.
- Runtime state propagation for how entitlements, access reads, and outbound events fit together.
- Outbound Licenzy webhooks for customer-facing event families and payload structure.
- Refund and dispute lifecycle for reversal and suspension behavior.
- Manual portal operations for operator-driven state changes.
What not to do
- Do not treat a browser success page as runtime proof of access.
- Do not treat outbound Licenzy events as raw forwarded Stripe events.
- Do not have your app call inbound Stripe webhook endpoints directly.
- Do not split runtime truth across your own inferred billing state and Licenzy entitlements.
