We're excited to announce that stripe-sync-engine is now available as a standalone npm package: @supabase/stripe-sync-engine!
Previously distributed only as a Docker image (supabase/stripe-sync-engine), you can now plug this into any backend project—whether you're using Node.js, running Express on a server, or even deploying on Supabase Edge Functions.
Stripe-Sync-Engine is a webhook listener that transforms Stripe webhooks into structured Postgres inserts/updates. It listens to Stripe webhook events (like invoice.payment_failed, customer.subscription.updated, etc), normalizes and stores them in a relational format in Postgres.
Why sync Stripe data to Postgres?#
While Supabase offers a convenient foreign data wrapper (FDW) for Stripe, sometimes you want your Stripe data locally available in your Postgres database for:
- Lower latency: Avoid round-trips to the Stripe API.
- Better joins: Query subscriptions, invoices, and charges together.
- Custom logic: Build fraud checks, billing dashboards, and dunning workflows directly from your own database.
You can now install and run the Stripe sync engine directly inside your backend:
_10
npm install @supabase/stripe-sync-engine
And use it like this:
_10
import { StripeSync } from '@supabase/stripe-sync-engine'
_10
_10
const sync = new StripeSync({
_10
databaseUrl: 'postgres://user:pass@host:port/db',
_10
stripeSecretKey: 'sk_test_...',
_10
stripeWebhookSecret: 'whsec_...',
_10
})
_10
_10
// Example: process a Stripe webhook
_10
await sync.processWebhook(payload, signature)
For a full list of configuration options, refer to our stripe-sync-engine README.
To use the Stripe-Sync-Engine in an Edge Function, you first have to ensure that the schema and tables exist. While you can technically do this inside the Edge Function, it is recommended to run the schema migrations outside of that. You can do a one-off migration via
_10
import { runMigrations } from '@supabase/stripe-sync-engine'
_10
;(async () => {
_10
await runMigrations({
_10
databaseUrl: 'postgresql://postgres:..@db.<ref>.supabase.co:5432/postgres',
_10
schema: 'stripe',
_10
logger: console,
_10
})
_10
})()
or include the migration files in your regular migration workflow.
Once the schema and tables are in place, you can start syncing your Stripe data using an Edge Function:
_31
import 'jsr:@supabase/functions-js/edge-runtime.d.ts'
_31
_31
import { StripeSync } from 'npm:@supabase/stripe-sync-engine@0.39.0'
_31
_31
// Load secrets from environment variables
_31
const databaseUrl = Deno.env.get('DATABASE_URL')!
_31
const stripeWebhookSecret = Deno.env.get('STRIPE_WEBHOOK_SECRET')!
_31
const stripeSecretKey = Deno.env.get('STRIPE_SECRET_KEY')!
_31
_31
// Initialize StripeSync
_31
const stripeSync = new StripeSync({
_31
databaseUrl,
_31
stripeWebhookSecret,
_31
stripeSecretKey,
_31
backfillRelatedEntities: false,
_31
autoExpandLists: true,
_31
})
_31
_31
Deno.serve(async (req) => {
_31
// Extract raw body as Uint8Array (buffer)
_31
const rawBody = new Uint8Array(await req.arrayBuffer())
_31
_31
const stripeSignature = req.headers.get('stripe-signature')
_31
_31
await stripeSync.processWebhook(rawBody, stripeSignature)
_31
_31
return new Response(null, {
_31
status: 202,
_31
headers: { 'Content-Type': 'application/json' },
_31
})
_31
})
- Deploy your Edge Function initially using
supabase functions deploy - Set up a Stripe webhook with the newly deployed Supabase Edge Function url
- Create a new .env file in the
supabasedirectory
_10
# Use Dedicated pooler if available
_10
DATABASE_URL="postgresql://postgres:..@db.<ref>.supabase.co:6532/postgres"
_10
STRIPE_WEBHOOK_SECRET="whsec_"
_10
STRIPE_SECRET_KEY="sk_test_..."
- Load the secrets using
sh supabase secrets set --env-file ./supabase/.env
As webhooks come in, the data is automatically persisted in the stripe schema. For a full guide, please refer to our repository docs.
If you're building with Stripe and Supabase, stripe-sync-engine gives you a reliable, scalable way to bring your billing data closer to your database and application. Whether you want better analytics, faster dunning workflows, or simpler integrations—this package is built to make that seamless.