BillingWebhookKit

Lemon Squeezy production webhook troubleshooting checklist

A live checkout page is only half of the revenue path. Before exposing a public buy link, prove that the paid event reaches the production endpoint, the x-signature gate trusts the exact raw body, fulfillment runs once, and refund rollback is tested.

Generate production readiness report

Work the production path in order

Do not debug fulfillment first. Most launch failures come from environment mismatch, stale endpoints, missing event subscriptions, signature verification on a parsed body, or no idempotency guard before side effects.

1. Match live checkout to live webhooks Confirm the production store, variant, CN¥69 price, PayPal checkout, endpoint URL, and webhook signing secret belong to the same live setup.
2. Require a paid order_created event For a one-time digital product, treat paid order evidence as the fulfillment trigger. Do not grant from checkout page visits or client callbacks.
3. Verify x-signature before parsing JSON Read the raw request body, verify HMAC, then parse. Public logs should show event IDs and object IDs, not secrets or customer data.
4. Write idempotency before delivery Persist a provider-scoped key before sending ZIP links, licenses, emails, or access grants so Lemon Squeezy retries cannot duplicate side effects.
5. Replay the same event three times The first delivery should process, later deliveries should skip. Keep evidence for checkout smoke tests and release review.
6. Test refund rollback separately Refund events should revoke or mark access according to policy without deleting audit evidence needed for buyer support.

Keep the public buy link disabled until this passes

If the live checkout is visible before webhook delivery, idempotency, private delivery, and refund rollback are proven, the buyer can pay while the product still needs manual recovery. Keep production checkout private until the launch report has no missing gates.

Evidence to capture before launch

Record the live checkout URL privately, the final paid event name, the production endpoint response, the idempotency key, the delivery artifact checksum, duplicate replay behavior, refund rollback behavior, and support policy link. This is enough to prove the path without publishing API keys, webhook secrets, customer emails, or private download URLs.

Use the browser-only reports to close the gaps

These tools generate copy-ready release evidence without calling Lemon Squeezy, Stripe, or any paid API.

PayPal live checkout report Track PayPal visibility, CN¥69 price, paid webhook delivery, x-signature, duplicate replay, private delivery, refund rollback, and owner approval. Fulfillment checklist generator Build a release report for signed paid events, private ZIP delivery, checksum evidence, idempotency, and support policy. Refund rollback report Document signed refund events, entitlement rollback, duplicate replay safety, support evidence, and secret-free review notes. View Pro Kit preview Prepared as a CN¥69 digital kit with fixtures, handlers, tests, CI checks, review reports, and launch checklists.

FAQ

What should I check first when a Lemon Squeezy live checkout succeeds but fulfillment fails?

First verify that the production checkout, store, product, variant, webhook endpoint, and subscribed events are all in the same live environment. Then confirm the paid order_created webhook arrived, x-signature verification passed against the exact raw body, and the fulfillment handler wrote the idempotency key before sending delivery.

Can I publish a Lemon Squeezy buy link before duplicate replay is tested?

No. Keep the public buy link disabled until a paid production event can be replayed multiple times while fulfillment, download delivery, email delivery, and license writes run only once.