Stripe Sync Engine Monorepo

This monorepo contains packages for synchronizing your Stripe account with a PostgreSQL database:

• stripe-experiment-sync: A TypeScript library for syncing Stripe data to PostgreSQL with managed webhooks, CLI tools, and Supabase Edge Function deployment.
• stripe-sync-fastify: A Fastify-based server and Docker image for production deployments.

---

Motivation

Sometimes you want to analyze your billing data using SQL. Even more importantly, you want to join your billing data to your product/business data.

This project synchronizes your Stripe account to a PostgreSQL database. It can be a new database, or an existing PostgreSQL database.

---

Quick Start

The easiest way to sync Stripe data to PostgreSQL:

import { StripeSync } from 'stripe-experiment-sync'

const sync = new StripeSync({
  poolConfig: {
    connectionString: process.env.DATABASE_URL,
    max: 10,
  },
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
})

// Create a managed webhook - automatically syncs all Stripe events
const webhook = await sync.findOrCreateManagedWebhook('https://example.com/stripe-webhooks')

// Cleanup when done
await sync.close()

Manual Webhook Processing

If you need to process webhooks in your own Express/Node.js app:

import express from 'express'
import { StripeSync } from 'stripe-experiment-sync'

const app = express()
const sync = new StripeSync({
  poolConfig: {
    connectionString: process.env.DATABASE_URL,
    max: 10,
  },
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
})

app.post('/stripe-webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['stripe-signature']

  try {
    await sync.processWebhook(req.body, signature)
    res.status(200).send({ received: true })
  } catch (error) {
    res.status(400).send({ error: error.message })
  }
})

app.listen(3000)

Supabase Edge Functions

Deploy to Supabase for serverless operation:

npx stripe-experiment-sync supabase install \
  --token $SUPABASE_ACCESS_TOKEN \
  --project $SUPABASE_PROJECT_REF \
  --stripe-key $STRIPE_API_KEY

CLI Commands

# Run database migrations
npx stripe-experiment-sync migrate --database-url $DATABASE_URL

# Start local sync with ngrok tunnel
npx stripe-experiment-sync start \
  --stripe-key $STRIPE_API_KEY \
  --ngrok-token $NGROK_AUTH_TOKEN \
  --database-url $DATABASE_URL

# Backfill historical data
npx stripe-experiment-sync backfill customer \
  --stripe-key $STRIPE_API_KEY \
  --database-url $DATABASE_URL

---

Configuration Options

Option	Type	Description
poolConfig	object	Required. PostgreSQL connection pool configuration. Supports connectionString, max, keepAlive.
stripeSecretKey	string	Required. Stripe secret key (sk_...)
stripeWebhookSecret	string	Stripe webhook signing secret (only needed for manual webhook processing)
stripeApiVersion	string	Stripe API version (default: 2020-08-27)
enableSigma	boolean	Enable Stripe Sigma reporting data sync. Default: false
autoExpandLists	boolean	Fetch all list items from Stripe (not just the default 10)
backfillRelatedEntities	boolean	Ensure related entities exist for foreign key integrity
revalidateObjectsViaStripeApi	Array	Always fetch latest data from Stripe instead of trusting webhook payload
maxRetries	number	Maximum retry attempts for 429 rate limits. Default: 5
initialRetryDelayMs	number	Initial retry delay in milliseconds. Default: 1000
maxRetryDelayMs	number	Maximum retry delay in milliseconds. Default: 60000
logger	Logger	Logger instance (pino-compatible)

---

How it works

• Automatically runs database migrations to create the stripe schema with tables matching Stripe objects.
• Creates managed webhooks in Stripe for automatic event synchronization.
• Processes webhook events and syncs data to PostgreSQL in real-time.
• Supports backfilling historical data from Stripe.
• Tracks sync runs and provides observability into sync operations.
• Built-in retry logic for rate limits and transient errors.

---

Packages

• Library & CLI: stripe-experiment-sync
• Docker/Server: stripe-sync-fastify

Each package has its own README with installation, configuration, and usage instructions.

---

Supabase Edge Function Deployment

Deploy the sync engine to Supabase Edge Functions for serverless operation with automatic webhook processing. See the sync-engine README for detailed instructions.

npx stripe-experiment-sync supabase install \
  --token $SUPABASE_ACCESS_TOKEN \
  --project $SUPABASE_PROJECT_REF \
  --stripe-key $STRIPE_API_KEY

---

Webhook Support

• balance.available
• charge.captured 🟢
• charge.expired 🟢
• charge.failed 🟢
• charge.pending 🟢
• charge.refunded 🟢
• charge.refund.updated 🟡 - For updates on all refunds, listen to refund.updated instead
• charge.succeeded 🟢
• charge.updated 🟢
• charge.dispute.closed 🟢
• charge.dispute.created 🟢
• charge.dispute.funds_reinstated 🟢
• charge.dispute.funds_withdrawn 🟢
• charge.dispute.updated 🟢
• checkout.session.async_payment_failed 🟢
• checkout.session.async_payment_succeeded 🟢
• checkout.session.completed 🟢
• credit_note.created 🟢
• credit_note.updated 🟢
• credit_note.voided 🟢
• customer.created 🟢
• customer.deleted 🟢
• customer.source.created
• customer.source.updated
• customer.subscription.created 🟢
• customer.subscription.deleted 🟢
• customer.subscription.paused 🟢
• customer.subscription.pending_update_applied 🟢
• customer.subscription.pending_update_expired 🟢
• customer.subscription.resumed 🟢
• customer.subscription.trial_will_end 🟢
• customer.subscription.updated 🟢
• customer.tax_id.created 🟢
• customer.tax_id.deleted 🟢
• customer.tax_id.updated 🟢
• customer.updated 🟢
• invoice.created 🟢
• invoice.deleted 🟢
• invoice.finalized 🟢
• invoice.finalization_failed 🟢
• invoice.marked_uncollectible 🟢
• invoice.paid 🟢
• invoice.payment_action_required 🟢
• invoice.payment_failed 🟢
• invoice.payment_succeeded 🟢
• invoice.sent 🟢
• invoice.upcoming 🔴 - Event has no id and cannot be processed
• invoice.updated 🟢
• invoice.overdue 🟢
• invoice.overpaid 🟢
• invoice.will_be_due 🟢
• invoice.voided 🟢
• issuing_authorization.request
• issuing_card.created
• issuing_cardholder.created
• payment_intent.amount_capturable_updated 🟢
• payment_intent.canceled 🟢
• payment_intent.created 🟢
• payment_intent.partially_refunded 🟢
• payment_intent.payment_failed 🟢
• payment_intent.processing 🟢
• payment_intent.requires_action 🟢
• payment_intent.succeeded 🟢
• payment_method.attached 🟢
• payment_method.automatically_updated 🟢
• payment_method.detached 🟢
• payment_method.updated 🟢
• plan.created 🟢
• plan.deleted 🟢
• plan.updated 🟢
• price.created 🟢
• price.deleted 🟢
• price.updated 🟢
• product.created 🟢
• product.deleted 🟢
• product.updated 🟢
• radar.early_fraud_warning.created 🟢
• radar.early_fraud_warning.updated 🟢
• refund.created 🟢
• refund.failed 🟢
• refund.updated 🟢
• review.opened 🟢
• review.closed 🟢
• setup_intent.canceled 🟢
• setup_intent.created 🟢
• setup_intent.requires_action 🟢
• setup_intent.setup_failed 🟢
• setup_intent.succeeded 🟢
• subscription_schedule.aborted 🟢
• subscription_schedule.canceled 🟢
• subscription_schedule.completed 🟢
• subscription_schedule.created 🟢
• subscription_schedule.expiring 🟢
• subscription_schedule.released 🟢
• subscription_schedule.updated 🟢
• entitlements.active_entitlement_summary.updated 🟢

---

Contributing

Issues and pull requests are welcome at https://github.com/stripe-experiments/sync-engine.

License

See LICENSE file.