Stripe webhooks in Supabase Edge Functions: common issues and solutions

If you run Stripe webhooks through a Supabase Edge Function, these are the common ways it breaks. They all end the same way: Stripe and your subscriptions table disagree about who's paying, and nothing alerts you.

1. Verifying the signature on a parsed body. Stripe signs the raw bytes. If you call `req.json()` before verifying, the check fails on every event. Read the body once with `await req.text()` and verify with `stripe.webhooks.constructEventAsync(body, signature, secret, undefined, Stripe.createSubtleCryptoProvider())`. It has to be the async variant, because Web Crypto is async. Then use the event it returns.
2. Test and live secrets mixed up. Every endpoint has its own signing secret, test and live mode are separate endpoints, and `stripe listen` gives you yet another one. A test secret on the live endpoint fails every signature check. If the endpoint's recent deliveries in Stripe are a wall of 400s, it's usually this.
3. Returning 200 before the write finishes. If the handler responds and then runs the update without awaiting it, Stripe records success and the write can still fail (or never run once the function shuts down). Await the write, check its error, then return 200. Return 500 on failure so Stripe retries.
4. JWT verification left on. Stripe doesn't send a Supabase JWT, so the function rejects every webhook with a 401. Deploy it with `supabase functions deploy stripe-webhook --no-verify-jwt` (or `verify_jwt = false` in `config.toml`) and rely on the Stripe signature instead.
5. The update succeeds and changes nothing. supabase-js doesn't treat "0 rows updated" as an error. Usual causes: the function uses the anon key and RLS silently filters the update (use the service role key in the webhook); `customer.subscription.updated` arrives before the row from checkout exists; or you look customers up by email and it doesn't match. Log the number of affected rows and treat 0 as a failure.
6. Missing events. If you only listen to `checkout.session.completed`, access gets granted and never removed. You also need `customer.subscription.updated` (plan changes, cancel at period end, past_due) and `customer.subscription.deleted` (the subscription actually ended). Add `charge.refunded` and `charge.dispute.created` if refunds or chargebacks should end access.

How to check what's broken: in the Stripe dashboard, open the webhook endpoint and read the recent deliveries (status code and response body). Then compare Stripe's active and canceled subscriptions against your table. A canceled customer who still has access in your table means 5 or 6.

Disclosure: I built a tool that does that comparison automatically. It uses a restricted read-only Stripe key and a read-only Postgres role (or a small read-only endpoint), never writes anywhere, and lists every customer the two sides disagree about with a suggested fix. The first scan is free, no account: