5. Update Webhooks

How Webhooks Work in BillStack

BillStack provides a per-team webhook endpoint that receives all Stripe events:

https://your-billstack.com/api/webhooks/stripe/{teamId}

When a Stripe event arrives:

1. BillStack verifies the stripe-signature header using your webhook secret
2. The stripe-sync-engine syncs the raw event data into your team's isolated schema
3. BillStack's webhook processor routes the event to the correct project based on customer metadata
4. Project-level tables (customers, subscriptions, invoices) are updated automatically
5. The event is recorded in the webhookEvents table for idempotency

Supported Events

BillStack processes these Stripe webhook events:

Step 1: Get Your Webhook URL

curl https://your-billstack.com/api/billstack/teams/{teamId}/stripe/webhook-url \
  -H "Cookie: <session-cookie>"

Response:

{
  "webhookUrl": "https://your-billstack.com/api/webhooks/stripe/team_abc123",
  "instructions": "Add this URL as an endpoint in your Stripe Dashboard"
}

Step 2: Configure in Stripe Dashboard

1. Go to Stripe Dashboard > Developers > Webhooks
2. Click Add endpoint
3. Paste your BillStack webhook URL
4. Select all events (or at minimum the events listed above)
5. Click Add endpoint
6. Copy the signing secret (whsec_...) shown after creation

Step 3: Update the Webhook Secret

If you used a placeholder webhook secret during Step 1: Connect Stripe, update it now:

curl -X POST https://your-billstack.com/api/billstack/teams/{teamId}/stripe/connect \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>" \
  -d '{
    "secretKey": "sk_live_...",
    "publishableKey": "pk_live_...",
    "webhookSecret": "whsec_actual_secret_from_stripe"
  }'

Step 4: Disable Your Old Webhook Endpoint

Once BillStack is receiving events:

1. Go back to Stripe Dashboard > Webhooks
2. Find your old webhook endpoint (the one pointing to your SaaS app directly)
3. Click ... > Disable (don't delete yet — keep it as a safety net)

Verifying Webhooks

Trigger a test event from the Stripe Dashboard:

1. Go to your webhook endpoint in Stripe
2. Click Send test webhook
3. Select an event type (e.g., customer.created)
4. Click Send test webhook

Then verify the event was processed:

curl https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/analytics \
  -H "Authorization: Bearer bs_..."

The webhookStats field in the analytics response shows total, processed, and failed event counts.

Keeping Your Old Webhooks (Transitional)

During migration, you can run both webhook endpoints simultaneously:

1. Keep your old endpoint active
2. Add the BillStack endpoint as a second endpoint
3. Stripe sends events to both
4. Once you've verified BillStack handles everything correctly, disable the old one

This allows a gradual transition with zero downtime.

Next Step

With webhooks configured, set up the customer portal to replace Stripe's hosted portal.