Stripe Webhook (Inbound)
Stripe webhook handling used internally for checkout activation, subscription plan changes, and subscription deletion.
Parsurai exposes an internal Stripe webhook receiver for billing events. This is distinct from outbound customer webhooks, which notify your own systems about extraction, review, and workflow events.
Stripe Webhook Endpoint
POST /webhooks/stripe
Stripe must send the Stripe-Signature header. Requests without a signature, or with an invalid
signature, return 400.
Local Development
stripe listen --forward-to localhost:8000/webhooks/stripe
Set the printed signing secret in the backend environment:
STRIPE_WEBHOOK_SECRET=whsec_your_local_signing_secret
Handled Events
| Event | Current backend behavior |
|---|---|
checkout.session.completed | Re-validates the business-details binding and charged plan, requires usable customer and subscription IDs, reconciles the event against Stripe's current non-terminal subscription, then creates or reactivates the paid account and persists stripe_subscription_id. A successful re-subscription also clears any pending account-deletion schedule. |
customer.subscription.updated | Applies a Stripe plan change only when the event's subscription ID still matches the subscription currently stored for the account. Delayed updates from an older subscription are ignored. |
customer.subscription.deleted | Cancels access and schedules 30-day account deletion only when the event matches the account's current subscription. The deletion write is subscription-scoped, so a delayed event for an older subscription cannot schedule deletion after re-subscription. |
Checkout activation does not create an API key. If email verification is still required, the activation flow issues or reuses a verification token; API-key creation remains part of the email-verification/key-management flow.
Other Stripe event types are acknowledged with {"received": true} but do not trigger account
updates. Handled events that are stale or do not match the account's current subscription are also
acknowledged without changing account state.
Security
The webhook verifies the Stripe signature with STRIPE_WEBHOOK_SECRET before parsing the event. Do not bypass signature verification in local or production setups.