lemonsqueezy-webhook-test

Skill: lemonsqueezy-webhook-test

Goal: Catch broken webhook handlers, signature mismatches and misrouted events before the first real customer hits checkout — against your handler, whatever framework it runs on.

Strategy

Lemon Squeezy has no official "send test webhook" API. This skill works around it by constructing webhook payloads itself and signing them with your shared secret, then POSTing them to your handler. It works against any endpoint where you control the secret — a local dev server (http://localhost:3000/...), a staging URL, or a preview deployment.

Inputs

webhookUrl: "http://localhost:3000/api/webhooks/lemonsqueezy"   # your handler
webhookSecret: "<your Lemon Squeezy webhook signing secret>"
events:                                # which events to exercise — pick your own
  - subscription_created
  - subscription_updated
  - order_created
customData: {}                         # optional arbitrary map merged into meta.custom_data
                                       #   e.g. { user_id: "user_123" } if your handler binds by user
signatureHeader: "X-Signature"         # optional override (Lemon Squeezy default)
eventHeader: "X-Event-Name"            # optional override (Lemon Squeezy default)
sampleVariantId: "555444"              # optional: variant id used in sub_* payload bodies

Only webhookUrl, webhookSecret and at least one event are required. The event list is entirely yours — Lemon Squeezy emits roughly a dozen event types (subscription_*, subscription_payment_*, order_created, license_key_*); exercise whichever your handler actually implements.

Workflow

1. Pre-flight checks
   • lemonsqueezy_list_webhooks to confirm a webhook is registered in the store
   • Compare the registered events array to your requested events — flag any you're testing that aren't actually subscribed
   • Display the registered URL for sanity (no localhost in production!)
2. Payload templates — for each event, build a JSON payload that mirrors what Lemon Squeezy would send (see examples/webhook-payloads.json in this repo for reference shapes). Merge customData into meta.custom_data when provided.
3. Signing — compute <signatureHeader> = HMAC-SHA256(rawBody, webhookSecret) as a hex digest.
4. POST — send each payload sequentially with headers:

   Content-Type: application/json
   <eventHeader>: <event>
   <signatureHeader>: <hex>
   

5. Assertions per event (handler-agnostic):
   • 2xx — handler accepted the payload
   • 401 — signature rejected (usually a secret mismatch)
   • any other non-2xx — handler-defined; surface the response body verbatim so the user can interpret it against their own logic
6. Report:
   • Event → status code → latency → pass/fail
   • Total latency budget (warn if any single handler > 2s)
   • Action items for failures