How It Works
When an event occurs, Kelviq creates aWebhookEvent and fans it out to all enabled endpoints you have registered for that event type. Each delivery is a single POST request with a JSON body and signed headers.
A delivery is considered successful when your endpoint returns a 2xx status code. Kelviq retries a delivery up to 3 times, with a 60-second delay between attempts, when the request fails to connect, times out after 10 seconds, or your endpoint returns a 5xx status code or 429 Too Many Requests. Other 4xx and 3xx responses are not retried; Kelviq does not follow redirects.
Registering an Endpoint
Go to Settings → Webhooks in the Kelviq dashboard to create a webhook endpoint. You will specify:- URL — The public HTTPS URL Kelviq will POST events to.
- Events — The subset of event types you want to subscribe to.
kq_whsec_<random>. Store this secret securely — you will need it to verify signatures.
Inspect and resend deliveries
Open Settings → Webhooks and select an endpoint to view its delivery logs. Each delivery shows the event type, status, response code, and response body. To retry a delivery:- Fix the endpoint or deployment issue that caused the delivery to fail.
- Open the failed delivery in the webhook logs.
- Click Resend.
- Review the new delivery attempt and its response.
5xx or 429 responses, but not other 4xx or 3xx responses. Use a manual resend to redeliver those after you fix the endpoint, or to retry immediately instead of waiting for the next automatic attempt.
Event Types
Checkout, subscription, and payment lifecycle
Checkout and subscription creation
checkout.completed confirms that checkout finished successfully, but it does not include subscription_id. Kelviq creates the subscription after checkout and sends its ID in subscription.created.
Use your customer identifier or checkout metadata to correlate the two events. See Add metadata to checkout for request and webhook examples. Do not treat the checkout redirect as proof that a subscription has been created.
Custom field responses
When a checkout session collects custom fields, the customer’s responses are included ascustom_fields_data in data.object of checkout.completed and of the order.created, order.updated, and order.refunded events for the resulting order. The object is keyed by custom field identifier and is empty ({}) when the session collected no custom fields.
Successful invoice payments
Kelviq sendsinvoice.paid whenever an invoice is paid, including invoices that are created directly with a PAID status. Use this event for payment-driven work such as recording revenue, starting an asynchronous provisioning job, or notifying an internal system.
For request-time access checks, query the customer’s current entitlements instead of relying on a local webhook-derived subscription state.
Failed invoice payments
Kelviq sendsinvoice.payment_failed when a subscription invoice payment fails or requires customer action. Use data.object.subscription_id and the embedded customer to identify the affected account. The invoice status is PAYMENT_FAILED for a failed attempt and can remain OPEN when the payment requires customer action.
This event can be followed by invoice.paid if the customer completes authentication or a later retry succeeds. Handle both events idempotently and treat the latest invoice and subscription state as authoritative.
Subscription end dates
Subscription webhook objects includeend_date inside data.object. Kelviq sets the field when a subscription has been cancelled or is scheduled to cancel on a future date. Otherwise, the value is null.
Use end_date for the subscription’s scheduled or final end. billing_period_end_time describes the current billing period instead and should not be treated as the subscription’s cancellation date.
Failed renewal payments
Kelviq does not currently send a separatepayment.failed event. For a failed card renewal:
- The subscription moves to
past_due. - Kelviq emails the customer a payment link.
- Kelviq sends
subscription.updatedwith the new subscription state. - Kelviq retries collection up to eight times over 14 days.
- If all recovery attempts fail, Kelviq cancels the subscription and sends
subscription.cancelled.
subscription.updated with past_due unless that is your own policy. Use the final subscription status or a live entitlement check to decide when access should end.
Card and UPI AutoPay renewals are retried for up to 14 days. If the payment still fails, the subscription is canceled.
Billing period field names
Subscription payloads usebilling_period_start_time and billing_period_end_time. Match these names exactly when parsing dates. They describe the current billing period; use end_date for the subscription’s scheduled or final end.
Plan changes
By default, Kelviq applies a plan change immediately, charges any prorated difference, and sendssubscription.plan_changed. After the generated invoice is paid, Kelviq sends the related order and invoice events.
If you update a subscription with paymentBehavior: "activate_on_payment", the existing subscription remains active while payment is pending. A payment method that requires customer action leaves the updated subscription in incomplete. After payment succeeds, the updated subscription becomes active and the previous subscription becomes superseded. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes incomplete_expired and the existing subscription remains active.
Do not provision the new plan from the update API response alone. Read the latest subscription status or query the customer’s current entitlements before changing access.
Pauses and resumes
A pause sendssubscription.paused with status: "paused", paused_at, and pause_resumes_at, which is null for an open-ended pause. Treat it like a cancellation for access: entitlement checks already return false for a paused customer, so clear any cached result when the event arrives (client.entitlements.invalidateCache in Node, client.entitlements.invalidate_cache in Python).
The subscription is quiet until it resumes. Renewals that fall inside the pause are skipped without subscription.updated or invoice events. subscription.resumed arrives when billing starts again, at the scheduled date or after a resume call, with status: "active" and a new billing period. Usage counters are reset at that point.
Both events fire whichever surface made the change: the dashboard, the customer portal, or your API call.
Partial and full refunds
order.refunded identifies whether the order is partially or fully refunded through its status:
PARTIAL_REFUNDfor a partial refundREFUNDEDfor a full refund
order.refunded payload does not include the refunded amount. Read amount or amount_units from refund.created and refund.updated when you need the exact value.
Request Headers
Every webhook request from Kelviq includes the following headers:Payload Structure
The request body is a JSON object with the following top-level fields:Example: checkout.completed payload
Example: checkout.completed payload
Example: customer.created payload
Example: customer.created payload
Example: customer.updated payload
Example: customer.updated payload
Example: order.created payload
Example: order.created payload
Example: order.updated payload
Example: order.updated payload
Example: order.refunded payload
Example: order.refunded payload
Example: subscription.created payload
Example: subscription.created payload
Example: subscription.updated payload
Example: subscription.updated payload
Example: subscription.cancelled payload
Example: subscription.cancelled payload
Example: subscription.plan_changed payload
Example: subscription.plan_changed payload
Example: subscription.paused payload
Example: subscription.paused payload
Example: subscription.resumed payload
Example: subscription.resumed payload
Example: subscription.trial_will_end payload
Example: subscription.trial_will_end payload
data.object uses the same subscription payload shape as subscription.created/subscription.updated; the trial’s remaining time is in trial_end. Kelviq sends this once, a few days before trial_end. It’s skipped if the subscription has already converted to active or has no trial days left.Example: feature.usage_alert payload
Example: feature.usage_alert payload
Example: invoice.created payload
Example: invoice.created payload
Example: invoice.paid payload
Example: invoice.paid payload
Example: invoice.payment_failed payload
Example: invoice.payment_failed payload
attempt_count, next_payment_attempt, and payment_link are also included on invoice.created and invoice.paid payloads. failure_details (with code, message, and payment_method_type) describes the most recent failed attempt and is null once the invoice moves past that attempt (e.g. a later invoice.paid for the same invoice). payment_link is null whenever the invoice isn’t currently payable (e.g. already paid).Example: refund.created payload
Example: refund.created payload
Example: refund.updated payload
Example: refund.updated payload
Example: payment_method.created payload
Example: payment_method.created payload
Example: payment_method.updated payload
Example: payment_method.updated payload
Example: payment_method.deleted payload
Example: payment_method.deleted payload
Verifying Signatures
Kelviq signs every request using HMAC-SHA256. To verify a request:- Read the
webhook-idandwebhook-timestampheaders. - Construct the signed string by concatenating:
{webhook-id}.{webhook-timestamp}.{raw-request-body}(joined with.) - Compute HMAC-SHA256 over the signed string using your endpoint’s signing secret as the key.
- Compare the hex digest to the signature in the
webhook-signatureheader (strip thev1,prefix before comparing). - Reject the request if the signatures do not match.
The raw request body must be used exactly as received — before any JSON parsing. The compact JSON serialization (no spaces) is what Kelviq sends and signs.
webhook-timestamp is within a few minutes of your server’s current time to defend against replay attacks.
Code Examples
Use
express.raw() (not express.json()) in Node.js so that req.body contains the unmodified request bytes. Parsing the body before verification will break the signature check. On a framework built on the Fetch API (Next.js route handlers, Hono, Remix, Cloudflare Workers), read the body with await request.text() and take each header with request.headers.get(...), since request.headers is a Headers object rather than a plain object.Best Practices
- Return
2xxfast. Acknowledge the webhook immediately and process it asynchronously. Long-running handlers increase the risk of timeouts and duplicate retries. - Make handlers idempotent. The same event may be delivered more than once. Use the top-level event
idor thewebhook-idheader as the deduplication key. - Validate the timestamp. Reject requests where
webhook-timestampis more than 5 minutes from your server’s clock to prevent replay attacks. - Use
hmac.compare_digest/hmac.Equal/crypto.timingSafeEqual. Constant-time comparison prevents timing side-channel attacks. - Store the raw body before parsing. Signature verification operates on the raw bytes, not the deserialized object.
Need Help?
- Email us at hi@kelviq.com
- Book a demo