Billing Webhooks
Principle
Section titled “Principle”A billing event matters only after the platform verifies it.
What the current implementation does
Section titled “What the current implementation does”In apps/api/src/routes/billing.ts, the webhook flow is:
- read the raw request body
- verify the webhook signature
- perform idempotency checks in
billing_webhook_events - map Polar state into internal entitlements
- update Supabase cache used by the product
Why this is important
Section titled “Why this is important”Without this step, the platform would be trusting external billing signals before converting them into its own verified state.
That would weaken the trust model.
The right way to explain it
Section titled “The right way to explain it”The docs should present webhook handling as the bridge between:
- external billing events
- trusted internal product access