Seven ways a license server quietly cuts off paying customers

Cancel is not revoke

Polar emits subscription.canceled when a customer switches off auto-renewal. It does not mean their access ends. They have paid through the end of the current period and they are entitled to every day of it. Only subscription.revoked means access ends now.

The naive handler treats both as "deactivate this license", because both read as bad news. So the customer cancels on day 3 of a 30-day period, and the software stops working on day 3. They did not ask for that, they paid for 30 days, and the message they see tells them to subscribe.

// Both are "cancel-shaped" events. Only one ends access.
CANCEL_EVENTS         = { subscription.canceled, subscription.revoked }
IMMEDIATE_REVOKE      = { subscription.revoked }
// canceled: stamp canceled_at, leave the license usable until expires_at.

The same bug walks back in through a different door

Having fixed the event path, there is a second path to the same row. A subscription.updated event carries a status field, and the handler decides activation from it. The obvious dead-status list reads revoked, unpaid, incomplete_expired, and it is very tempting to add canceled.

Adding it recreates incident one exactly. Polar sets status: canceled the moment renewal is switched off, while current_period_end is still in the future and the customer is still entitled. So the fix on the event path was undone by the status path, for the same customers, with the same symptom.

Two secrets that look alike and hash differently

Polar signs webhooks with the Standard Webhooks scheme: HMAC-SHA256 over id.timestamp.body. The trap is the key.

• A secret copied from the Polar dashboard looks like polar_whs_..., and the HMAC key is the raw UTF-8 bytes of the whole string, prefix included. Polar's own validator base64-encodes the secret before handing it to the Standard Webhooks library, which decodes it straight back.
• A secret minted through POST /v1/webhooks/endpoints comes back as whsec_<base64>, the canonical shape, where the key is the base64-decoded remainder.

Both are valid. Both are handed to you by the same vendor. Pick the wrong one and every signature fails, every webhook is rejected with a 401 that only your logs see, and the first sale produces nothing. Polar retries, the retries also fail, and the customer emails you.

// Two extra HMACs on a request you were going to reject anyway.
candidateKeys(secret) =
  [ utf8(secret) ]                       // dashboard shape
  + [ base64decode(after first "_") ]    // API shape, when it decodes

Every event goes to every endpoint

Polar delivers each event to every webhook endpoint registered in the organization. If you sell two products from one org, your license server sees the other product's sales and, unguarded, provisions for them. That is not a theoretical leak. It is a stranger receiving an email containing a working license key for software they never heard of.

The guard is a product id allowlist. The subtlety is reading the id: it has arrived as product_id, as productId, and nested under product.id. A guard that checks one shape returns null on the others, and a null id falls through to "provision it", which is exactly the behaviour you were guarding against.

resolveProductId(data) =
  data.product_id ?? data.productId ?? data.product?.id ?? null

There is a deliberate hole in ours: an event with no product id at all is treated as ours. Legacy subscriptions still arrive in a payload shape that omits it, and a false negative here costs a paying customer their key. That asymmetry is the whole design principle of the file.

Grace for renewals, never for trials

Renewals reach you as a webhook that pushes expires_at forward. If that delivery is late or dropped, the old expiry is already in the past, and a customer who paid this morning is demoted to the free tier this afternoon. A few days of grace after expiry costs nothing and prevents a support ticket, or a cancellation, caused entirely by your own plumbing.

Then two exclusions, both learned after the fact:

• Trials get no grace. A trial has no renewal, so there is no webhook that can be late. Grace here is just a longer trial that you did not decide to offer.
• Cancelled subscriptions get no grace. Renewal is switched off, so again there is no webhook coming. The customer keeps exactly the time they paid for, which is the correct answer in both directions.

if (!active)                 -> unusable
if (expiry >= now)           -> usable
if (source === "trial")      -> unusable   // nothing to be late
if (canceled_at)             -> unusable   // no renewal coming
if (now <= expiry + 4 days)  -> usable, in grace
                             -> expired

Retries arrive out of order and resurrect the dead

Cancelling in Polar emits canceled and revoked back to back. Webhook delivery is at-least-once and not ordered, so an ordinary retry of the earlier subscription.updated, still carrying the pre-cancellation state, lands after revoked has switched the row off and writes active = 1 straight back. No attacker involved. Just a retry.

Status alone cannot fix this, because the retried event's status is genuinely live: it was live when the event was generated. Two things do fix it.

• Stamp revoked_at when revocation happens and guard the upsert with WHERE revoked_at IS NULL. Revocation is terminal.
• Refuse to activate when the paid period has already ended, whatever the status says. That also stops a cycled or updated replayed long after a subscription lapsed.

shouldBeActive(status, currentPeriodEnd, now):
  if (deadStatus(status))        return 0
  if (!currentPeriodEnd)         return 1
  return currentPeriodEnd > now ? 1 : 0

The trial key that outlives the trial

Anyone who converts mid-trial holds two rows: the trial they started and the subscription they bought. Every lookup that returns "their key" now has to choose, and newest-first is wrong. It hands a paying customer their dead trial key, which validates as free tier and looks exactly like a broken product.

Worse, the trial key is already sitting in their config file. It keeps working until day 8, so conversion is a trap with a delayed trigger: they pay, nothing changes, everything looks fine, and a week later their agent tells them to subscribe.

pickLookupRow(rows, now):
  usable = rows.filter(isUsable)
  return usable.find(r => r.source !== "trial") ?? usable[0] ?? null

The fix is two-sided. Lookups prefer the paid row, and the trial endpoint checks for a paid row first and hands back the subscription key so it replaces the trial key in place. Matched on the machine fingerprint alone, deliberately: requiring the same email on both rows stranded everyone who trialled with a personal address and checked out with a work one.

What this adds up to

None of these are hard problems. Every one of them is a two-line fix. What makes them expensive is that they all fail silently in the direction of the customer, and none of them show up in a test you would think to write, because the input that triggers them is a webhook from a vendor behaving exactly as documented.

The version of this you write on day one is the naive version, and the naive version quietly takes access away from people who paid. You will not find out for weeks. That is the actual lesson, and it is why the file is 428 lines: 224 of code, and 164 of comments explaining which incident put each branch there.

There are now 180 unit tests, 39 HTTP checks against a database migrated from the live table shape, 21 checks driving the built server over stdio, and 16 lifecycle checks pushing real signed webhooks through a local worker. Almost all of them were written after an incident, not before one.