Webhook events

The normalized webhook event union, the exact provider events each one maps from, the signature schemes, and how provider detection works.

A complete reference of what parseWebhookEvent produces for every provider event it recognizes. For verification, the raw-body rule, and idempotency, see Webhooks.

The normalized union

type WebhookEventType =
  | 'subscription.created'
  | 'subscription.updated'
  | 'subscription.canceled'
  | 'order.paid'
  | 'checkout.completed'
  | 'license.issued'
  | 'unknown';

Every parsed event also carries providerType — the provider’s original event string — raw, the untouched envelope, idempotencyKey (always set), and, where the provider supplies them, subscriptionChange and createdAt. Anything not listed below comes back as unknown; parseWebhookEvent never throws on an unrecognized type.

The finer-grained transition a provider named lives in the separate subscriptionChange field, not in type.

The matrix

subscription.created

subscription.updated

subscription.canceled (terminal)

order.paid

The attached Order is mapped exactly as the orders namespace maps it — status, createdAt, and refundStatus included — and order.id is the ID client.orders.get and client.orders.getInvoiceUrl take. A delivery you missed can be recovered with orders.list; see Orders.

checkout.completed

license.issued

Issuance is the only normalized license event. Revocation and updates are not mapped — the three providers disagree too much to normalize; License keys explains why and what to do instead.

Subscription changes

type is the coarse classification that stays honest on all five providers. subscriptionChange is the finer one: which lifecycle transition the provider’s event string named, or undefined where it named none. It is only ever set on subscription.updated.

type SubscriptionChange = 'cancel_scheduled' | 'past_due' | 'paused' | 'resumed' | 'uncanceled';

The dashes are the point: coverage is genuinely uneven, and subscriptionChange reports that honestly instead of inventing a transition. It is derived only from the provider’s event string, never from payload state — cancelAtPeriodEnd stays true for the rest of the period, so a payload-derived transition would re-announce the same “cancellation scheduled” on every later event. Every event still carries the full Subscription, so the current state is always available regardless of whether a transition was named.

Which model each event carries

WebhookEvent is a discriminated union on type, so this table is enforced by the type system: narrow on event.type and the payload below is a required field — no optional-field guessing, no !.

Independent of the type, every event carries type, providerType, raw and idempotencyKey, plus createdAt on every provider except Lemon Squeezy — see Idempotency for where the key comes from and what it does and does not protect against.

Signature schemes

verifyWebhook returns false (never throws) for a missing header, a stale timestamp, a malformed secret, or a mismatched signature, and all comparisons are constant-time.

Provider detection

detectWebhookProvider inspects headers, then the body when it has to: