Webhooks and System Sync
Synchronize Clerk users and Stripe payments with verified, idempotent webhook handling.
Synchronize Clerk users and Stripe payments with verified, idempotent webhook handling.
- Enable observability for requests and failures.
- Run replay checks before policy changes.
- Set alert thresholds for error and fallback rate.
- Document rollback steps for incidents.
Endpoints
| Source | Endpoint | Purpose |
|---|---|---|
| Clerk | /api/webhooks/clerk | User lifecycle sync |
| Stripe | /api/webhooks/stripe | Subscription and add-on checkout settlement |
Clerk events handled
user.created— create the local user record for the free previewuser.updated— sync email and name changesuser.deleted— deactivate user account
Clerk webhooks are verified using Svix signatures. If the auth middleware already auto-created the user before the webhook arrives, the webhook gracefully updates instead of duplicating.
Stripe events handled
checkout.session.completed— subscription or add-on fulfillmentcheckout.session.async_payment_succeeded— delayed payment confirmation
Both events trigger the same fulfillment flow: validate metadata, check idempotency, and apply the correct subscription or add-on state. Events are deduplicated by stripe_payment_id to prevent double-crediting.
Sync hardening
Setup checklist
- Configure webhook endpoints in Clerk and Stripe dashboards.
- Set webhook secrets in environment variables.
- Send test events and verify logs.
- Validate duplicate event handling.
Never run webhook handlers without signature verification. Treat all inbound webhook traffic as untrusted until verified.
ChatKit-style guided help
Product-scoped assistant for LLMWise docs and API usage. It does not answer unrelated topics.
Sign in to ask implementation questions and get runnable snippets.
Sign in to use assistant