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 | Checkout settlement to wallet credits |
Clerk events handled
user.created— create local user with signup bonus (40 free credits)user.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— wallet top-up fulfillmentcheckout.session.async_payment_succeeded— delayed payment confirmation
Both events trigger the same fulfillment flow: validate metadata, check idempotency, and credit the user wallet. 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