POST /webhooks/clerk-billing
Receives subscription lifecycle events from kenbun's billing provider. This endpoint is called automatically by the billing system -- you do not need to call it yourself. It is documented here so that administrators understand what events drive subscription status changes in kenbun.
What This Endpoint Does
When your organization's subscription changes — a trial starts, a payment succeeds, a payment fails, or a subscription is canceled — the billing provider sends a webhook event to this endpoint. kenbun processes the event and updates your organization's subscription status accordingly.
This is what causes the status badge on Settings > Billing to update from Trial to Active, or from Active to Past Due.
Subscription Events Processed
| Event | What Triggers It | Result in kenbun |
|---|---|---|
subscription.created | New subscription started (including trial) | Status set to Active or Trial |
subscription.updated | Payment succeeded, plan changed, or status changed | Status updated to reflect new state |
subscriptionItem.freeTrialEnding | Trial is about to expire | Reminder notification sent |
payment_attempt | A payment was attempted (success or failure) | Payment failures are reflected in the next subscription.updated event |
Subscription Statuses
The following subscription statuses can be set by these events. See Billing and Subscription for a full explanation of what each status means for your access:
| Status | Meaning |
|---|---|
active | Subscription is in good standing |
trialing | Organization is in the free trial period |
past_due | A payment attempt failed |
canceled | Subscription was canceled |
ended | Subscription period has ended |
Security
All webhook requests from the billing provider are authenticated using a signed payload. kenbun verifies the signature on every incoming request and rejects any request that fails verification or that arrives more than 5 minutes after it was sent (to prevent replay attacks). You do not need to configure anything for this to work.
Related Pages
- Billing and Subscription — How subscriptions and statuses work for end-users
- Usage API — Check your organization's current event usage