DEV Community

Cover image for Stripe-To-Postgres Sync Engine as standalone Library
Yuri for Supabase

Posted on • Originally published at supabase.com

15 13 12 13 13

Stripe-To-Postgres Sync Engine as standalone Library

We're excited to announce that stripe-sync-engine is now available as a standalone npm package: @supabase/stripe-sync-engine!

command to use

⚡️ More on Launch Week

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.

visual process

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.

New: Use it as an npm package

You can now install and run the Stripe sync engine directly inside your backend:

npm install @supabase/stripe-sync-engine
Enter fullscreen mode Exit fullscreen mode

And use it like this:

import { StripeSync } from '@supabase/stripe-sync-engine'

const sync = new StripeSync({
  databaseUrl: 'postgres://user:pass@host:port/db',
  stripeSecretKey: 'sk_test_...',
  stripeWebhookSecret: 'whsec_...',
})

// Example: process a Stripe webhook
await sync.processWebhook(payload, signature)

Enter fullscreen mode Exit fullscreen mode

For a full list of configuration options, refer to our stripe-sync-engine README.

Use via Supabase Edge Function

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

import { runMigrations } from '@supabase/stripe-sync-engine'
;(async () => {
  await runMigrations({
    databaseUrl: 'postgresql://postgres:..@db.<ref>.supabase.co:5432/postgres',
    schema: 'stripe',
    logger: console,
  })
})()

Enter fullscreen mode Exit fullscreen mode

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:

import 'jsr:@supabase/functions-js/edge-runtime.d.ts'
import { StripeSync } from 'npm:@supabase/stripe-sync-engine@0.39.0'

// Load secrets from environment variables
const databaseUrl = Deno.env.get('DATABASE_URL')!
const stripeWebhookSecret = Deno.env.get('STRIPE_WEBHOOK_SECRET')!
const stripeSecretKey = Deno.env.get('STRIPE_SECRET_KEY')!

// Initialize StripeSync
const stripeSync = new StripeSync({
  databaseUrl,
  stripeWebhookSecret,
  stripeSecretKey,
  backfillRelatedEntities: false,
  autoExpandLists: true,
})

Deno.serve(async (req) => {
  // Extract raw body as Uint8Array (buffer)
  const rawBody = new Uint8Array(await req.arrayBuffer())

  const stripeSignature = req.headers.get('stripe-signature')

  await stripeSync.processWebhook(rawBody, stripeSignature)

  return new Response(null, {
    status: 202,
    headers: { 'Content-Type': 'application/json' },
  })
})

Enter fullscreen mode Exit fullscreen mode
  1. Deploy your Edge Function initially using supabase functions deploy
  2. Set up a Stripe webhook with the newly deployed Supabase Edge Function url
  3. Create a new .env file in the supabase directory
# Use Dedicated pooler if available
DATABASE_URL="postgresql://postgres:..@db.<ref>.supabase.co:6532/postgres"
STRIPE_WEBHOOK_SECRET="whsec_"
STRIPE_SECRET_KEY="sk_test_..."

Enter fullscreen mode Exit fullscreen mode
  1. 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.

Final thoughts

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.

Launch Week 15

Main Stage

Day 1 - Introducing JWT Signing Keys
Day 2 - Introducing Supabase Analytics Buckets with Iceberg Support

Build Stage

Worldwide Community Meetups

Scale globally with MongoDB Atlas. Try free.

Scale globally with MongoDB Atlas. Try free.

MongoDB Atlas is the global, multi-cloud database for modern apps trusted by developers and enterprises to build, scale, and run cutting-edge applications, with automated scaling, built-in security, and 125+ cloud regions.

Learn More

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.

Gen AI apps are built with MongoDB Atlas

Gen AI apps are built with MongoDB Atlas

MongoDB Atlas is the developer-friendly database for building, scaling, and running gen AI & LLM apps—no separate vector DB needed. Enjoy native vector search, 115+ regions, and flexible document modeling. Build AI faster, all in one place.

Start Free

👋 Kindness is contagious

Explore this insightful write-up embraced by the inclusive DEV Community. Tech enthusiasts of all skill levels can contribute insights and expand our shared knowledge.

Spreading a simple "thank you" uplifts creators—let them know your thoughts in the discussion below!

At DEV, collaborative learning fuels growth and forges stronger connections. If this piece resonated with you, a brief note of thanks goes a long way.

Okay