Webhooks
Inbound
/api/v1/webhooks/clerk- syncs user + workspace state via Svix signature verification./api/v1/webhooks/stripe- subscription + invoice + checkout events. See Credits + billing for the credit grant rules.
Outbound
Outbound webhooks ship with the public API in Sprint 17. The shape is
already declared on workflows.trigger.type='webhook' so workflow runs
can be triggered remotely with a shared secret hash.
Stripe handler events
| Event | What we do |
| --- | --- |
| checkout.session.completed | If kind=topup, credit the workspace wallet. |
| customer.subscription.created/updated | Upsert subscription row, mirror plan onto workspaces.plan, grant monthly allocation on first activation. |
| customer.subscription.deleted | Mark canceled, drop workspace to free. |
| invoice.paid / invoice.payment_succeeded | Mirror invoice row, grant plan_renewal credits on cycle invoices. |
| invoice.payment_failed | Mirror invoice with status=open. |
Idempotency is enforced by existing-row checks before insert. The handler re-throws on internal failures so Stripe retries.