Setting up Stripe webhooks (live)

Purchases only provision after Stripe tells FastStaq the payment succeeded. That signal is the webhook. If the live webhook is missing or misconfigured, customers pay but nothing unlocks. Set this up carefully.

The endpoint URL

FastStaq accepts the Stripe webhook at:

https://api.yourdomain.com/webhooks/stripe

Two aliases also route to the same handler if you prefer them: /api/v1/subscription/webhook and /api/v1/stripe/webhook. Use the API domain, not the front-end domain.

Step 1: Create the live endpoint

1. In the Stripe Dashboard, switch to live mode.
2. Go to Developers -> Webhooks -> Add endpoint.
3. Enter your endpoint URL from above.

Step 2: Subscribe to events

Select the events FastStaq handles:

• checkout.session.completed (provisions one-time/lifetime purchases)
• invoice.payment_succeeded
• invoice.payment_failed
• customer.subscription.updated
• customer.subscription.deleted
• charge.refunded
• charge.dispute.created
• price.created, price.updated, price.deleted, product.updated

Step 3: Copy the signing secret

After creating the endpoint, Stripe shows a Signing secret that starts with whsec_.... Put it in your production env:

STRIPE_WEBHOOK_SECRET=whsec_...

Restart the API so it picks up the new secret. The signature check fails if this does not match the live endpoint.

Step 4: Verify

1. Make a small real purchase in live mode.
2. In the Stripe webhook view, confirm the event was delivered with a 200 response.
3. Confirm the buyer's /dashboard/purchase shows access unlocked.

Local development

For local testing, use the Stripe CLI to forward events to your machine:

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

The CLI prints a whsec_... secret to use in your local server/.env.

Common pitfalls

• Wrong mode: a test-mode webhook will not fire for live payments. Create a separate live endpoint.
• Secret mismatch: each endpoint has its own signing secret; copy the live one.
• Pointing at the front-end domain: use the API domain.

Related articles

• Configure Stripe payments
• Billing and subscriptions module
• Troubleshooting common issues

Still need help?

Open a support ticket with the failing event ID from Stripe.