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.

---

Quick Start

The easiest way to sync Stripe data to PostgreSQL is using the CLI. It will run a full historical backfill, and optionally stay alive to stream real-time events.

CLI (Webhook Mode)

npx stripe-experiment-sync sync \
  --stripe-key $STRIPE_API_KEY \
  --database-url $DATABASE_URL \
  --listen-mode webhook \
  --ngrok-token $NGROK_AUTH_TOKEN

CLI (Websocket Mode)

npx stripe-experiment-sync sync \
  --stripe-key $STRIPE_API_KEY \
  --database-url $DATABASE_URL \
  --listen-mode websocket

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

---

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
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 syncing historical data from Stripe.
• Tracks sync runs and provides observability into sync operations.

---

Packages

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

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

---

Webhook Support

For the full event matrix (supported, unsupported, and caveats), see docs/webhook-event-support.md.

Syncing Data

For the current supported Stripe object types, see packages/sync-engine/README.md#syncing-data.

---

Contributing

Issues and pull requests are welcome at stripe-experiments/sync-engine.

License

See LICENSE file.