Guide
Stripe and Supabase entitlement synchronization
How to keep Stripe billing state and Supabase application access aligned, with secure credential storage, signed event ingestion, and reconciliation.
Architecture overview
A typical SaaS application uses Stripe for billing and Supabase (or another database) for application state, including user roles and feature access. The challenge is keeping these two systems in sync.
SubSync Guard connects to both systems read-only, takes periodic snapshots, and produces advisory findings when they disagree. This guide explains the patterns and pitfalls.
Secure credential storage
Store Stripe API keys and Supabase service-role keys server-side only, encrypted at rest. Never expose them in the browser or in client bundles.
- Use a server-side encryption key (e.g.,
CREDENTIAL_ENCRYPTION_KEY) to encrypt connector secrets before storing them. - Decrypt only inside Edge Functions or server-side code.
- Rotate keys with a migration plan — rotating invalidates all stored secrets.
Signed event ingestion
When Stripe sends webhooks or Supabase receives events, verify authenticity before processing:
- HMAC signatures: Verify the webhook signature using Stripe's signing secret. Reject requests with invalid or missing signatures.
- Replay protection: Store a nonce or timestamp for each event. Reject events that have already been processed or are too old.
- Idempotency: Use a unique constraint on the event ID. Process each event exactly once.
- Rate limiting: Protect endpoints from abuse with per-IP or per-key rate limits.
Entitlement snapshots
Periodically capture the application's access state for each customer:
- Record which customers have premium access, which plan they're on, and when it expires.
- Store snapshots with timestamps for historical comparison.
- Use idempotent snapshot writes to avoid duplicates on retry.
Reconciliation
Compare Stripe subscription state with application entitlements:
| Stripe status | App access | Finding | Severity |
|---|---|---|---|
| canceled | premium | Canceled but still has premium access | High |
| active | free | Active subscription but only free access | High |
| past_due | premium | Past due but still has premium access | Review |
| trialing | premium | Trial customer with premium access | Info |
Common failure modes
- Missed webhooks: Stripe events not delivered or not processed. Use reconciliation as a safety net.
- Stale cache: Application caches subscription status and doesn't invalidate on updates.
- Race conditions: Events arrive out of order, causing temporary mismatches.
- Multiple subscriptions: Customer has multiple subscriptions; system checks the wrong one.
- Grace period logic: Application grants access past period end due to incorrect calculation.
How SubSync Guard helps
SubSync Guard connects to your Stripe account (read-only) and your Supabase application. It takes periodic snapshots, runs reconciliation, and produces advisory findings for every mismatch. Findings include both identifiers, snapshot times, and the policy applied.
No automatic revocation — your team decides what to change. Every finding is reviewable, resolvable, and auditable.