License and Webhook Operations

What this guide is for

This guide is for internal operators who need to understand how license state flows from Lemon Squeezy into the backend and how that affects paid features.

Main integration flow

1. a user activates or binds a license
2. the backend stores normalized license fields
3. Lemon Squeezy sends subscription and license key webhook events
4. the backend updates subscription and license state
5. config endpoints convert those states into feature gating

Important webhook route

The production webhook endpoint should point to:

/api/v1/webhooks/lemonsqueezy

If the URL points at the wrong host or root path, Lemon Squeezy may show successful delivery failures such as 405 Method Not Allowed.

How feature locking works

Paid features are controlled by both:

• license validity
• subscription status

That means an active key alone is not enough if the subscription state is blocked.

Recovery and repair

If a license snapshot becomes inconsistent, operators should:

1. confirm webhook delivery
2. confirm the latest subscriptions and licenses rows
3. use repair tooling or replay only when needed

Why this document matters

This is the internal layer that reduces support pressure. When operators understand the state model, they can tell the difference between:

• a user setup problem
• a webhook sync problem
• a paid entitlement problem