Lemon Squeezy webhook idempotency
A Lemon Squeezy webhook handler should verify the raw-body signature, derive a stable idempotency key, and skip duplicate deliveries before granting access twice.
Open the free idempotency testerPick the key after signature verification
Do not trust event names, order IDs, customer IDs, or subscription IDs until the x-signature header matches the exact raw request body. After verification, combine the provider, event name, and stable object ID.
Store before the side effect
Insert the idempotency key in a processed-event table before sending license keys, provisioning seats, sending receipts, or updating subscription state. If the insert finds an existing key, return success and skip the side effect.
Test retries with duplicate fixtures
Run the same Lemon Squeezy fixture three times in a Vitest or integration test. The expected result is one processed side effect and two duplicate skips.
FAQ
Do Lemon Squeezy webhooks need idempotency?
Yes. Any payment webhook can be retried or delivered more than once, so handlers should store a stable event key before running billing side effects.
What is a safe Lemon Squeezy webhook idempotency key?
A safe key combines the provider, event name, and stable object identifier, for example lemon_squeezy:order_created:order_id or lemon_squeezy:subscription_payment_success:invoice_id.
Use the free sample before wiring production checkout
Download a public sample pack with fake Lemon Squeezy fixtures, signature tests, contract checks, duplicate replay tests, and CI skeletons. The Pro Kit preview shows the full paid package structure without exposing the private archive.