digital-identity-platform-docs

---

digital-identity-platform-docs / supabase/functions/stripe-webhook

supabase/functions/stripe-webhook

Fileoverview

Stripe Webhook Edge Function

Handles incoming Stripe webhook events to keep subscription state in sync. Processes checkout completions, subscription updates, and cancellations.

Cloudflare Architecture Context

Attribute	Value
Classification	🔵 BACKEND-ONLY
Position	External Callback (Stripe → Supabase)
Receives Public Traffic	Yes (from Stripe webhook infrastructure)
Latency Sensitive	Yes (Stripe has timeout limits)
Safe to Retry	Yes (Stripe retries failed webhooks)
Failure Behavior	Return error (Stripe will retry)

Endpoint

POST /stripe-webhook

Auth

Stripe signature verification (not JWT)

Remarks

This function is called by Stripe when subscription events occur. It verifies the webhook signature and updates the database accordingly.

Handled events:

• checkout.session.completed: Creates/updates subscription after successful checkout
• customer.subscription.updated: Syncs plan changes and cancellation state
• customer.subscription.deleted: Resets user to Free plan
• invoice.payment_failed: Marks subscription as past_due
• invoice.paid: Reactivates subscription after payment recovery
• payment_method.attached: Auto-upgrades paused containers when payment method is added

Tables touched:

• sgtm_container_subscriptions (upsert/update)
• clients (update external_customer_id)
• billing_plans (read for plan lookup)

Environment variables required:

• STRIPE_SECRET_KEY: Stripe API secret key
• STRIPE_WEBHOOK_SECRET: Webhook endpoint signing secret
• SUPABASE_URL: Supabase project URL
• SUPABASE_SERVICE_ROLE_KEY: Service role key for admin operations

Type Aliases

• StripeWebhookModule