Stripe Plugin

Complete Stripe billing and payments integration for nself. Syncs all Stripe data to PostgreSQL with real-time webhook support.

Overview

The Stripe plugin provides complete synchronization of your Stripe account data to a local PostgreSQL database. It supports:

• 21 Database Tables - complete coverage of Stripe objects
• 70+ Webhook Events - Real-time updates for all Stripe events
• 6 Analytics Views - Pre-built SQL views for common metrics
• Full REST API - Query synced data via HTTP endpoints
• CLI Interface - Manage everything from the command line

Quick Start

# Install the plugin
nself plugin install stripe

# Configure environment
echo "STRIPE_API_KEY=sk_live_xxx" >> .env
echo "STRIPE_WEBHOOK_SECRET=whsec_xxx" >> .env

# Rebuild and restart to apply
nself build && nself restart

# Verify the plugin is running
nself plugin status stripe

Configuration

Environment Variables

API Key Permissions

Your Stripe API key needs read access to all resources you want to sync. Write access is not required (plugin is read-only). For production, use a restricted key with only read permissions.

CLI Commands

Plugin Lifecycle

# Install the stripe plugin
nself plugin install stripe

# Check plugin health and sync status
nself plugin status stripe

# Update to latest version
nself plugin update stripe

# Remove plugin (keeps tables by default)
nself plugin remove stripe

# Remove plugin and drop all stripe_* tables
nself plugin remove stripe --delete-data

Data Access

Stripe data syncs automatically via webhook handlers the plugin registers at install time. For a historical backfill after initial setup, use the Stripe Dashboard export or the Stripe CLI — the nself plugin does not expose per-resource sync subcommands.

Query synced data directly via Hasura GraphQL (all tables are auto-tracked):

# List customers
query {
  stripe_customers(limit: 50) {
    id
    email
    name
    created
  }
}

# List active subscriptions
query {
  stripe_subscriptions(where: { status: { _eq: "active" } }) {
    id
    customer_id
    status
    current_period_end
  }
}

# List recent invoices
query {
  stripe_invoices(order_by: { created: desc }, limit: 20) {
    id
    customer_id
    status
    amount_due
    amount_paid
  }
}

Webhook Setup

The plugin registers a webhook endpoint at /webhooks/stripe on your nself backend. Configure it in the Stripe Dashboard to start receiving real-time events — see the Webhook Setup section below.

Troubleshooting Sync

# Check that the plugin container is healthy
nself plugin status stripe

# Tail plugin logs for webhook delivery errors
nself plugin logs stripe

# Re-enable a disabled plugin
nself plugin enable stripe

Webhook Setup

Stripe Dashboard

1. Go to Stripe Dashboard > Webhooks
2. Add endpoint: https://your-domain.com/webhooks/stripe
3. Select events to subscribe:
   • customer.created, customer.updated
   • subscription.created, subscription.updated, subscription.deleted
   • invoice.paid, invoice.payment_failed
   • payment_intent.succeeded, payment_intent.payment_failed
4. Copy signing secret to STRIPE_WEBHOOK_SECRET

Stripe CLI (Development)

stripe listen --forward-to localhost/webhooks/stripe

Synced Resources

Analytics Views

Example Queries

-- Monthly recurring revenue from Stripe
SELECT
    DATE_TRUNC('month', created_at) AS month,
    SUM(amount / 100.0) AS mrr
FROM stripe_subscriptions
WHERE status = 'active'
GROUP BY month
ORDER BY month DESC;

-- Find customers at risk of churn
SELECT
    c.email,
    c.name,
    s.current_period_end,
    s.cancel_at_period_end,
    i.amount / 100.0 AS last_invoice_amount,
    i.status AS last_invoice_status
FROM stripe_customers c
JOIN stripe_subscriptions s ON c.id = s.customer_id
LEFT JOIN stripe_invoices i ON s.latest_invoice = i.id
WHERE s.status = 'active'
  AND (
      s.cancel_at_period_end = TRUE
      OR i.status IN ('open', 'uncollectible')
      OR s.current_period_end < NOW() + INTERVAL '7 days'
  )
ORDER BY s.current_period_end;

-- Revenue report by product
SELECT
    pr.name AS product_name,
    p.nickname AS price_name,
    p.unit_amount / 100.0 AS price,
    p.currency,
    COUNT(DISTINCT s.id) AS active_subscriptions,
    SUM(p.unit_amount) / 100.0 AS total_mrr
FROM stripe_products pr
JOIN stripe_prices p ON pr.id = p.product_id
JOIN stripe_subscription_items si ON p.id = si.price_id
JOIN stripe_subscriptions s ON si.subscription_id = s.id
WHERE s.status = 'active'
GROUP BY pr.name, p.nickname, p.unit_amount, p.currency
ORDER BY total_mrr DESC;

GraphQL Access

All Stripe tables are automatically tracked in Hasura:

query GetCustomerSubscriptions {
  stripe_customers(limit: 10) {
    id
    email
    name
    stripe_subscriptions {
      id
      status
      current_period_end
      stripe_price {
        unit_amount
        stripe_product {
          name
        }
      }
    }
  }
}

Environment Handling

Development (Test Mode)

ENV=dev
STRIPE_API_KEY=sk_test_xxxxx

Uses test customers, no real charges.

Production (Live Mode)

ENV=prod
STRIPE_API_KEY=sk_live_xxxxx

Real customer data and charges.

Uninstall

# Remove plugin and data
nself plugin remove stripe

# Keep database tables
nself plugin remove stripe --keep-data

Troubleshooting

Invalid API Key

Error: Invalid API Key provided

Check that STRIPE_API_KEY is set correctly. Ensure you are using the correct key for your environment (test vs live).

# Verify key format
echo $STRIPE_API_KEY | head -c 10
# Should show: sk_live_xx or sk_test_xx

Webhook Signature Verification Failed

Error: Webhook signature verification failed

Solutions:

1. Verify STRIPE_WEBHOOK_SECRET matches the endpoint in Stripe Dashboard
2. Ensure you are using the raw request body for verification
3. Check that the webhook endpoint URL is correct

Rate Limit Exceeded

Error: Rate limit exceeded

The plugin has built-in rate limiting, but if you are hitting limits:

1. Use incremental sync instead of full sync
2. Reduce concurrent operations
3. Check for other applications using the same API key

Database Connection Failed

Error: Connection refused

Solutions:

1. Verify PostgreSQL is running
2. Check DATABASE_URL format
3. Verify database exists and user has permissions

# Test connection
psql $DATABASE_URL -c "SELECT 1"

Debug Mode

Enable debug logging for detailed troubleshooting:

# Tail live plugin logs (shows webhook delivery details)
nself plugin logs stripe

# Check plugin status and container health
nself plugin status stripe

Health Checks

# Check plugin status
nself plugin status stripe

# Check plugin container health via HTTP (port exposed by plugin service)
curl http://localhost:3001/health

Integration Examples

Link Stripe Customer to App User

-- Create a view to join app users with Stripe customers
CREATE VIEW user_billing AS
SELECT
  u.id AS user_id,
  u.email,
  sc.id AS stripe_customer_id,
  sc.created AS customer_since,
  (SELECT COUNT(*) FROM stripe_subscriptions ss
   WHERE ss.customer_id = sc.id AND ss.status = 'active') AS active_subscriptions
FROM users u
LEFT JOIN stripe_customers sc ON u.email = sc.email;

Subscription Status Check

// Check if user has active subscription
async function hasActiveSubscription(userEmail: string): Promise<boolean> {
  const result = await hasura.query({
    query: `
      query CheckSubscription($email: String!) {
        stripe_customers(where: { email: { _eq: $email } }) {
          stripe_subscriptions(where: { status: { _eq: "active" } }) {
            id
          }
        }
      }
    `,
    variables: { email: userEmail }
  });

  return result.stripe_customers[0]?.stripe_subscriptions?.length > 0;
}

Support

• GitHub Issues: nself-plugins/issues
• Stripe Documentation: stripe.com/docs/api
• Stripe API Changelog: stripe.com/docs/upgrades

Related

• Plugin Overview - Plugin system introduction
• Plugin Installation - Install and manage plugins
• Plugin Development - Create your own plugins

Last Updated: April 2026 | Plugin Version 1.0.12 | Stripe API Version 2024-12-18