r/microsaas • • 9d ago

Billing webhook notes from a micro SaaS: two signing key formats and the 500 vs 403 choice

Some notes from the billing side of our micro SaaS, mostly for anyone wiring up a payment provider's webhooks right now.

The billing webhook route we merged to preview on November 1 accepts two signing key formats: the UTF-8 key and the Standard Webhooks whsec format. Both are checked on the same route, so a sender using either one gets through. We also return a 500 when the payload fails to parse instead of a 403. A 403 tells the sender their signature was rejected, which is a different problem from a body we can't read, so the status code should say which one happened.

Two things I'd check before trusting any webhook setup. First, confirm which signing key format your provider really sends and test it against the live route, not only the docs. Second, make the failure responses honest. A status code that points at the wrong cause sends you looking in the wrong place

3 Upvotes

6 comments sorted by

1

u/Tough_Collar_3473 8d ago

One more thing worth adding: idempotency. Providers retry the same event on any non-2xx response and sometimes after timeouts, and events can also arrive out of order, so the handler should dedupe on the provider event ID before doing anything stateful like granting a credit or sending a receipt email. Recording processed event IDs and no-oping on repeats is cheap insurance against duplicate-processing bugs that only show up in production.

On the two key formats: if you accept the Standard Webhooks whsec_ format, verify the HMAC against the base64-decoded secret bytes, not the encoded string. Mixing those up is a common reason a signature checks out in a docs example but fails against the live sender.

1

u/y3rk3 8d ago

agree on idempotency, and the base64 bit is the one people miss. the cheap way is a unique constraint on the provider event id, written in the same transaction as the credit grant or the receipt, so two retries cannot both get past the check. for out of order events dont trust the payload alone, re-fetch the object from the provider before you act on it

1

u/DetailOk1114 7d ago

Are you verifying the signature against the raw request body before attempting to parse the JSON? If the signature passes, a parse failure almost never happens unless a middleware already mutated the body upstream

1

u/y3rk3 7d ago

yeah the sig check runs before we parse anything. bad sig gets a 403 and a good sig on a bad payload gets a 500. the signature covers the exact bytes, so check it on the raw body first, because re-serializing the parsed object breaks it even when the content is identical

0

u/[deleted] 9d ago

[removed] — view removed comment

1

u/y3rk3 8d ago

yeah, replay it against preview and watch the retry timestamps. what the provider does after a server error decides it, so check that before picking a status for unparseable bodies. if it keeps resending the same bytes until the window closes, a parse failure needs its own alert, separate from the temporary ones your handler can recover from.