Skip to content
HookDeploy

Lemon Squeezy webhooks

Last verified against Lemon Squeezy's documentation on September 27, 2026.

On this page ↓

Lemon Squeezy sends webhooks when something happens in your store: an order is placed, a subscription starts, renews, or is cancelled, a payment fails, or a license key is created. It signs each request with an HMAC of the raw body. Most problems come from verifying a parsed body, mixing up test mode and live mode webhooks, or granting access twice when a webhook is retried. This page covers what Lemon Squeezy sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Lemon Squeezy sends webhooks for

AreaExample eventsTypical use
Ordersorder_created, order_refundedFulfill purchases and handle refunds
Subscriptionssubscription_created, subscription_updated, subscription_cancelled, subscription_expired, subscription_resumedKeep access in sync
Subscription paymentssubscription_payment_success, subscription_payment_failed, subscription_payment_recoveredTrack renewals and dunning
License keyslicense_key_created, license_key_updatedDeliver and manage licenses

Each webhook is a JSON POST. The event name is in meta.event_name and the X-Event-Name header, any custom data you passed at checkout is in meta.custom_data, and the object is under data.

How Lemon Squeezy delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body
Signature headerX-Signature: hex HMAC-SHA256 of the raw body, keyed with the webhook’s signing secret
Event headerX-Event-Name
SuccessAny 2xx
RetriesDeliveries that don’t get a 2xx are retried
Test modeTest mode and live mode have separate webhooks and signing secrets

Common Lemon Squeezy webhook errors and how to fix them

Signature never matches

  • Parsed body. Hash the raw bytes, then parse.
  • Wrong secret. Each webhook has its own signing secret, and test mode and live mode are configured separately.
  • Unsafe comparison. Compare with a constant-time function, and check lengths first, since timingSafeEqual throws on unequal lengths.

Access granted twice

Retries deliver the same event again. Record which orders and subscription events you’ve processed, and skip repeats.

Can’t match the webhook to your user

Pass your user ID as custom data at checkout. It comes back in meta.custom_data on the related webhooks.

Events work in test mode but not live

Live mode needs its own webhook, with its own signing secret.

Why use HookDeploy with Lemon Squeezy

Capture every event

HookDeploy captures every Lemon Squeezy webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down, the events wait in HookDeploy instead of depending on Lemon Squeezy’s retries.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

One webhook, many systems

Send each Lemon Squeezy event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Lemon Squeezy can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Lemon Squeezy events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Lemon Squeezy events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then the signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Lemon Squeezy treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Lemon Squeezy’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and X-Signature header unchanged, so retries and replays verify like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks the signature.

The same event can arrive more than once. Make fulfillment idempotent, keyed on the order or subscription and the event name.

Set up Lemon Squeezy with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Lemon Squeezy live) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. In Lemon Squeezy, go to Settings, then Webhooks, and add a webhook with your HookDeploy URL, a signing secret, and your events. Do this separately for test mode and live mode.
  4. Make a test purchase in test mode, and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/lemon-squeezy', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.LEMONSQUEEZY_WEBHOOK_SECRET)
    .update(req.body)                          // raw bytes
    .digest('hex');
  const received = req.get('x-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({
    name: event.meta.event_name,
    objectId: event.data.id,
    userId: event.meta.custom_data?.user_id,
  });
  // Deduplicate on objectId plus name in your worker.
});

FAQ

How do I verify a Lemon Squeezy webhook?

Compute a hex HMAC-SHA256 of the raw request body using the webhook's signing secret, and compare it to the X-Signature header with a constant-time comparison.

Why does my Lemon Squeezy signature check fail?

Usually because the body was parsed before verification, or because the secret belongs to the other mode. Test mode and live mode have separate webhooks and secrets.

How do I link a Lemon Squeezy webhook to my user?

Pass your user ID as custom data when you create the checkout. It's returned in meta.custom_data on the order and subscription webhooks.

Does Lemon Squeezy retry failed webhooks?

Yes. Deliveries that don't get a 2xx response are retried, so your handler should be idempotent.

Where is the event type in a Lemon Squeezy webhook?

In the X-Event-Name header and in meta.event_name in the body.

Does HookDeploy break Lemon Squeezy signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and X-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Lemon Squeezy webhooks free

Start free