@kelviq/mcp-server 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
@@ -0,0 +1,963 @@
1
+ ---
2
+ title: "Webhooks"
3
+ slug: "guides/webhooks"
4
+ section: "guides"
5
+ description: "Receive real-time event notifications from Kelviq to your server."
6
+ ---
7
+ Kelviq can push event notifications to your server whenever something meaningful happens — a subscription is created, an invoice is paid, or a refund is issued. This guide explains how to register an endpoint, verify incoming requests, and handle events.
8
+
9
+ ---
10
+
11
+ ## How It Works
12
+
13
+ When an event occurs, Kelviq creates a `WebhookEvent` 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.
14
+
15
+ Kelviq retries failed deliveries up to **3 times** with a 60-second delay between attempts. A delivery is considered successful when your endpoint returns a `2xx` status code.
16
+
17
+ ---
18
+
19
+ ## Registering an Endpoint
20
+
21
+ Go to **Settings → Webhooks** in the [Kelviq dashboard](https://app.kelviq.com/settings/webhooks/new) to create a webhook endpoint. You will specify:
22
+
23
+ - **URL** — The public HTTPS URL Kelviq will POST events to.
24
+ - **Events** — The subset of event types you want to subscribe to.
25
+
26
+ After creation, Kelviq generates a signing secret for the endpoint in the format `kq_whsec_<random>`. Store this secret securely — you will need it to verify signatures.
27
+
28
+ Your signing secret is shown only once. If you lose it, you must regenerate it from the dashboard.
29
+
30
+ ---
31
+
32
+ ## Event Types
33
+
34
+ | Event | Description |
35
+ |-------|-------------|
36
+ | `checkout.completed` | A customer successfully completed a checkout session and payment was collected. |
37
+ | `customer.created` | A new customer record was created in your organization. |
38
+ | `customer.updated` | A customer's profile data (name, email, metadata) was updated. |
39
+ | `order.created` | A new order was placed. |
40
+ | `order.updated` | An existing order was updated. |
41
+ | `order.refunded` | A full or partial refund was issued against an order. |
42
+ | `subscription.created` | A new subscription was activated for a customer. |
43
+ | `subscription.updated` | A subscription's details were modified. |
44
+ | `subscription.cancelled` | A subscription was cancelled (immediately or at period end). |
45
+ | `subscription.plan_changed` | A subscription was moved to a different plan. |
46
+ | `feature.usage_alert` | A customer's feature usage crossed a configured threshold. |
47
+ | `invoice.created` | A new invoice was generated. |
48
+ | `invoice.paid` | An invoice was paid and funds were collected. |
49
+ | `refund.created` | A refund was initiated. |
50
+ | `refund.updated` | A refund's status changed (e.g., from pending to completed). |
51
+
52
+ ---
53
+
54
+ ## Request Headers
55
+
56
+ Every webhook request from Kelviq includes the following headers:
57
+
58
+ | Header | Description |
59
+ |--------|-------------|
60
+ | `webhook-id` | A unique UUID identifying this specific webhook event delivery. |
61
+ | `webhook-timestamp` | Unix timestamp (seconds) of when the event was dispatched. |
62
+ | `webhook-signature` | HMAC-SHA256 signature. Format: `v1,{signature}` |
63
+ | `Content-Type` | Always `application/json`. |
64
+
65
+ ---
66
+
67
+ ## Payload Structure
68
+
69
+ The request body is a JSON object with the following top-level fields:
70
+
71
+ ```json
72
+ {
73
+ "id": "3a7f1c2d-8e4b-4a9f-b123-0e5d6c7a8b9e",
74
+ "type": "subscription.created",
75
+ "created_at": "2024-06-01T12:00:00Z",
76
+ "data": {
77
+ "object": { ... },
78
+ "previous_attributes": { ... }
79
+ }
80
+ }
81
+ ```
82
+
83
+ | Field | Type | Description |
84
+ |-------|------|-------------|
85
+ | `id` | `string` (UUID) | The unique ID of this event. Matches the `webhook-id` header. |
86
+ | `type` | `string` | The event type (e.g., `subscription.created`). |
87
+ | `created_at` | `string` (ISO 8601) | UTC timestamp of when the event was created. |
88
+ | `data.object` | `object` | The primary resource affected by the event. |
89
+ | `data.previous_attributes` | `object` | *(Update events only)* The resource's changed attributes before the event. Omitted if not applicable. |
90
+
91
+ ```json
92
+ {
93
+ "id": "1619afec-caab-40c7-827c-6af4f3acc9a3",
94
+ "type": "checkout.completed",
95
+ "created_at": "2026-04-01T17:28:39Z",
96
+ "data": {
97
+ "object": {
98
+ "id": "cs_jBy6ViggULoyDMW9ikaw4ydur1NUa6dCORT6vqKPbPPW8",
99
+ "object": "checkout_session",
100
+ "status": "success",
101
+ "checkout_type": "ONE_TIME",
102
+ "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
103
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
104
+ "amount": "10.00",
105
+ "amount_units": 1000,
106
+ "currency": "USD",
107
+ "discount_code": "",
108
+ "features": null,
109
+ "plan": {
110
+ "name": "Exc Tax Plan",
111
+ "version": 1,
112
+ "identifier": "exc-tax-plan"
113
+ },
114
+ "product": {
115
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
116
+ "name": "ParityDeals"
117
+ },
118
+ "billing_address": {
119
+ "line1": null,
120
+ "line2": null,
121
+ "city": null,
122
+ "state": null,
123
+ "postal_code": "680121",
124
+ "country": "IN"
125
+ },
126
+ "metadata": {
127
+ "name": "Geo",
128
+ "email": "geojacob@example.com",
129
+ "referer": null,
130
+ "cancel_url": null,
131
+ "success_url": null,
132
+ "tax_behavior": "EXCLUSIVE",
133
+ "discounts_enabled": true
134
+ },
135
+ "created_on": "2026-04-01T17:27:59Z",
136
+ "modified_on": "2026-04-01T17:28:39Z"
137
+ }
138
+ }
139
+ }
140
+ ```
141
+
142
+ ```json
143
+ {
144
+ "id": "0662641a-b415-46eb-a78a-c136ce12fa60",
145
+ "type": "customer.created",
146
+ "created_at": "2026-04-01T07:05:56Z",
147
+ "data": {
148
+ "object": {
149
+ "id": "7dd79eff-180f-4b07-a213-ebafd29e9725",
150
+ "object": "customer",
151
+ "customer_id": "geo-jacob",
152
+ "name": "Geo Jacob",
153
+ "email": "geo@example.com",
154
+ "details": {},
155
+ "metadata": {},
156
+ "billing_address": {},
157
+ "subscriptions": 0,
158
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
159
+ "created_on": "2026-04-01T07:05:56Z",
160
+ "modified_on": "2026-04-01T07:05:56Z"
161
+ }
162
+ }
163
+ }
164
+ ```
165
+
166
+ ```json
167
+ {
168
+ "id": "221a4d03-1cf4-47ae-9ed8-9f8f79ae989d",
169
+ "type": "customer.updated",
170
+ "created_at": "2026-04-01T07:32:42Z",
171
+ "data": {
172
+ "object": {
173
+ "id": "7dd79eff-180f-4b07-a213-ebafd29e9725",
174
+ "object": "customer",
175
+ "customer_id": "geo-jacob",
176
+ "name": "Geo Jacob v2",
177
+ "email": "geo@example.com",
178
+ "details": {},
179
+ "metadata": {},
180
+ "billing_address": {},
181
+ "subscriptions": 0,
182
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
183
+ "created_on": "2026-04-01T07:05:56Z",
184
+ "modified_on": "2026-04-01T07:32:42Z"
185
+ },
186
+ "previous_attributes": {
187
+ "name": "Geo Jacob"
188
+ }
189
+ }
190
+ }
191
+ ```
192
+
193
+ ```json
194
+ {
195
+ "id": "evt_01HXYZ1234567890ABCDEF",
196
+ "type": "order.created",
197
+ "created_at": "2026-04-01T17:36:41Z",
198
+ "data": {
199
+ "object": {
200
+ "id": "ORD-20260401173639-H8IO7",
201
+ "object": "order",
202
+ "status": "COMPLETE",
203
+ "billing_type": "ONE_TIME",
204
+ "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
205
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
206
+ "is_renewal": false,
207
+ "paid_at": "2026-04-01T17:36:41Z",
208
+ "amount_total": "10.00",
209
+ "amount_total_units": 1000,
210
+ "currency": "USD",
211
+ "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
212
+ "product": {
213
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
214
+ "name": "ParityDeals"
215
+ },
216
+ "plan": {
217
+ "name": "Exc Tax Plan",
218
+ "version": 1,
219
+ "identifier": "exc-tax-plan"
220
+ },
221
+ "features": null,
222
+ "created_on": "2026-04-01T17:36:41Z",
223
+ "modified_on": "2026-04-01T17:36:41Z"
224
+ }
225
+ }
226
+ }
227
+ ```
228
+
229
+ ```json
230
+ {
231
+ "id": "evt_01HXYZ2345678901BCDEFG",
232
+ "type": "order.updated",
233
+ "created_at": "2026-04-01T17:36:41Z",
234
+ "data": {
235
+ "object": {
236
+ "id": "ORD-20260401173639-H8IO7",
237
+ "object": "order",
238
+ "status": "COMPLETE",
239
+ "billing_type": "ONE_TIME",
240
+ "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
241
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
242
+ "is_renewal": false,
243
+ "paid_at": "2026-04-01T17:36:41Z",
244
+ "amount_total": "10.00",
245
+ "amount_total_units": 1000,
246
+ "currency": "USD",
247
+ "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
248
+ "product": {
249
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
250
+ "name": "ParityDeals"
251
+ },
252
+ "plan": {
253
+ "name": "Exc Tax Plan",
254
+ "version": 1,
255
+ "identifier": "exc-tax-plan"
256
+ },
257
+ "features": null,
258
+ "created_on": "2026-04-01T17:36:41Z",
259
+ "modified_on": "2026-04-01T17:36:41Z"
260
+ },
261
+ "previous_attributes": {
262
+ "status": "PENDING"
263
+ }
264
+ }
265
+ }
266
+ ```
267
+
268
+ ```json
269
+ {
270
+ "id": "c1fb8514-fec6-44fa-9196-7dabe2f153ac",
271
+ "type": "order.refunded",
272
+ "created_at": "2026-04-02T03:48:32Z",
273
+ "data": {
274
+ "object": {
275
+ "id": "ORD-20260401173639-H8IO7",
276
+ "object": "order",
277
+ "status": "REFUNDED",
278
+ "billing_type": "ONE_TIME",
279
+ "customer_id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
280
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
281
+ "is_renewal": false,
282
+ "paid_at": "2026-04-01T17:36:41Z",
283
+ "amount_total": "10.00",
284
+ "amount_total_units": 1000,
285
+ "currency": "USD",
286
+ "subscription_id": "2c78e8f0-892e-406c-9896-18c69d3026c4",
287
+ "product": {
288
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
289
+ "name": "ParityDeals"
290
+ },
291
+ "plan": {
292
+ "name": "Exc Tax Plan",
293
+ "version": 1,
294
+ "identifier": "exc-tax-plan"
295
+ },
296
+ "features": null,
297
+ "created_on": "2026-04-01T17:36:41Z",
298
+ "modified_on": "2026-04-02T03:48:32Z"
299
+ },
300
+ "previous_attributes": {
301
+ "status": "COMPLETE"
302
+ }
303
+ }
304
+ }
305
+ ```
306
+
307
+ ```json
308
+ {
309
+ "id": "3a7f1c2d-8e4b-4a9f-b123-0e5d6c7a8b9e",
310
+ "type": "subscription.created",
311
+ "created_at": "2026-03-11T05:25:34Z",
312
+ "data": {
313
+ "object": {
314
+ "id": "a22f1b2a-b922-4a28-9b0e-75e826988b4b",
315
+ "object": "subscription",
316
+ "status": "active",
317
+ "plan": {
318
+ "name": "default pd",
319
+ "version": 1,
320
+ "identifier": "default-pd"
321
+ },
322
+ "product": {
323
+ "id": "b4ea7e75-5dbe-4b3b-96e0-9a31dfe5a600",
324
+ "name": "Migrate PD"
325
+ },
326
+ "amount": "21.24",
327
+ "amount_units": 2100,
328
+ "currency": "USD",
329
+ "recurrence": "1 month",
330
+ "start_date": "2026-03-11",
331
+ "end_date": null,
332
+ "billing_period_start_time": "2026-03-11T05:25:33Z",
333
+ "billing_period_end_time": "2026-04-10T06:28:58Z",
334
+ "customer": {
335
+ "id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
336
+ "name": "Geo Jacob",
337
+ "email": "geo@example.com",
338
+ "customer_id": "1",
339
+ "billing_address": {
340
+ "city": "Bangalore",
341
+ "line1": null,
342
+ "line2": null,
343
+ "state": "Karnataka",
344
+ "country": "IN",
345
+ "postal_code": "560001"
346
+ }
347
+ },
348
+ "features": null,
349
+ "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
350
+ "created_on": "2026-03-11T05:25:34Z",
351
+ "modified_on": "2026-03-11T05:25:34Z"
352
+ }
353
+ }
354
+ }
355
+ ```
356
+
357
+ ```json
358
+ {
359
+ "id": "be4b0fa8-2e82-4664-b4f8-c3ab1622086c",
360
+ "type": "subscription.updated",
361
+ "created_at": "2026-04-02T05:21:33Z",
362
+ "data": {
363
+ "object": {
364
+ "id": "ff258fd6-9a31-4eda-b3c8-000a24530890",
365
+ "object": "subscription",
366
+ "status": "active",
367
+ "amount": "40.00",
368
+ "amount_units": 4000,
369
+ "currency": "USD",
370
+ "recurrence": "1 month",
371
+ "start_date": "2026-04-02",
372
+ "end_date": null,
373
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
374
+ "features": null,
375
+ "plan": {
376
+ "name": "Inc tax sub",
377
+ "version": 1,
378
+ "identifier": "inc-tax-sub"
379
+ },
380
+ "product": {
381
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
382
+ "name": "ParityDeals"
383
+ },
384
+ "customer": {
385
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
386
+ "name": "Geo Jacob",
387
+ "email": "geojacob@example.com",
388
+ "customer_id": "bc43b1a034a643309ee39d2f1a4d2131",
389
+ "billing_address": {
390
+ "line1": null,
391
+ "line2": null,
392
+ "city": null,
393
+ "state": null,
394
+ "postal_code": "680121",
395
+ "country": "IN"
396
+ }
397
+ },
398
+ "billing_period_start_time": "2026-04-02T05:04:43Z",
399
+ "billing_period_end_time": "2026-05-02T05:04:43Z",
400
+ "created_on": "2026-04-02T05:21:28Z",
401
+ "modified_on": "2026-04-02T05:21:33Z"
402
+ },
403
+ "previous_attributes": {
404
+ "status": null,
405
+ "billing_period_start_time": null
406
+ }
407
+ }
408
+ }
409
+ ```
410
+
411
+ ```json
412
+ {
413
+ "id": "cacae554-d67e-4c6c-9d51-9d68f5c9b574",
414
+ "type": "subscription.cancelled",
415
+ "created_at": "2026-04-02T05:02:47Z",
416
+ "data": {
417
+ "object": {
418
+ "id": "0faa77b7-2d42-4b6f-b682-d012987adad2",
419
+ "object": "subscription",
420
+ "status": "canceled",
421
+ "amount": "40.00",
422
+ "amount_units": 4000,
423
+ "currency": "USD",
424
+ "recurrence": "1 month",
425
+ "start_date": "2026-04-02",
426
+ "end_date": "2026-05-02",
427
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
428
+ "features": null,
429
+ "plan": {
430
+ "name": "Inc tax sub",
431
+ "version": 1,
432
+ "identifier": "inc-tax-sub"
433
+ },
434
+ "product": {
435
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
436
+ "name": "ParityDeals"
437
+ },
438
+ "customer": {
439
+ "id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
440
+ "name": "Geo Jacob",
441
+ "email": "geojacob@example.com",
442
+ "customer_id": "bc43b1a034a643309ee39d2f1a4d2131",
443
+ "billing_address": {
444
+ "line1": null,
445
+ "line2": null,
446
+ "city": null,
447
+ "state": null,
448
+ "postal_code": "680121",
449
+ "country": "IN"
450
+ }
451
+ },
452
+ "billing_period_start_time": "2026-04-02T04:25:13Z",
453
+ "billing_period_end_time": "2026-05-02T04:25:13Z",
454
+ "created_on": "2026-04-02T04:25:20Z",
455
+ "modified_on": "2026-04-02T05:02:47Z"
456
+ },
457
+ "previous_attributes": {
458
+ "status": "active"
459
+ }
460
+ }
461
+ }
462
+ ```
463
+
464
+ ```json
465
+ {
466
+ "id": "b9c2e1f0-7d3a-4b8e-a456-1f2g3h4i5j6k",
467
+ "type": "subscription.plan_changed",
468
+ "created_at": "2026-03-04T11:53:12Z",
469
+ "data": {
470
+ "object": {
471
+ "id": "d1284180-beba-465a-b756-9a300324245e",
472
+ "object": "subscription",
473
+ "status": "active",
474
+ "plan": {
475
+ "name": "Pro",
476
+ "version": 4,
477
+ "identifier": "pro"
478
+ },
479
+ "product": {
480
+ "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
481
+ "name": "demo"
482
+ },
483
+ "amount": "29.00",
484
+ "amount_units": 2900,
485
+ "currency": "USD",
486
+ "recurrence": "1 month",
487
+ "start_date": "2026-02-26",
488
+ "end_date": null,
489
+ "billing_period_start_time": "2026-02-26T05:25:11Z",
490
+ "billing_period_end_time": "2026-03-26T05:25:11Z",
491
+ "customer": {
492
+ "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
493
+ "name": "Geo",
494
+ "email": "geo@example.com",
495
+ "customer_id": "geo123",
496
+ "billing_address": {}
497
+ },
498
+ "features": null,
499
+ "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
500
+ "created_on": "2026-03-04T11:53:12Z",
501
+ "modified_on": "2026-03-04T11:53:14Z"
502
+ },
503
+ "previous_attributes": {
504
+ "id": "065ee4e2-b643-4f78-bac0-9bd4afcba963",
505
+ "object": "subscription",
506
+ "status": "active",
507
+ "plan": {
508
+ "name": "Enterprise",
509
+ "version": 1,
510
+ "identifier": "enterprise"
511
+ },
512
+ "product": {
513
+ "id": "988dba89-0a96-4cb5-870a-34810011c1f1",
514
+ "name": "demo"
515
+ },
516
+ "amount": "99.00",
517
+ "amount_units": 9900,
518
+ "currency": "USD",
519
+ "recurrence": "1 month",
520
+ "start_date": "2026-02-26",
521
+ "end_date": null,
522
+ "billing_period_start_time": "2026-02-26T05:25:11Z",
523
+ "billing_period_end_time": "2026-03-26T05:25:11Z",
524
+ "customer": {
525
+ "id": "798e663f-2fe9-43d7-879f-2549263e20d1",
526
+ "name": "Geo",
527
+ "email": "geo@example.com",
528
+ "customer_id": "geo123",
529
+ "billing_address": {}
530
+ },
531
+ "features": null,
532
+ "organization": "5d0bec80-a7c1-41ae-bd24-ea9228500586",
533
+ "created_on": "2026-03-04T11:29:19Z",
534
+ "modified_on": "2026-03-04T11:29:23Z"
535
+ }
536
+ }
537
+ }
538
+ ```
539
+
540
+ ```json
541
+ {
542
+ "id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
543
+ "type": "feature.usage_alert",
544
+ "created_at": "2026-05-18T18:48:59Z",
545
+ "data": {
546
+ "object": {
547
+ "id": "a1c88c9d-19cf-48cc-b194-6cc6ebb356ee",
548
+ "object": "feature_usage_alert",
549
+ "feature": {
550
+ "id": "245d745f-28ca-4856-81fe-1e1f5c6c7ebd",
551
+ "name": "API calls",
552
+ "identifier": "api-calls",
553
+ "feature_type": "METER"
554
+ },
555
+ "customer": {
556
+ "id": "d2b6c9ac-bcd5-4e59-8c7e-b6472485e112",
557
+ "name": "Geo",
558
+ "email": "geo@example.com",
559
+ "customer_id": "fcec7a06c7484584b8a4d92711bfe528",
560
+ "billing_address": {
561
+ "city": null,
562
+ "line1": null,
563
+ "line2": null,
564
+ "state": null,
565
+ "country": "IN",
566
+ "postal_code": "680121"
567
+ }
568
+ },
569
+ "usage_limit": 5,
570
+ "current_usage": 5,
571
+ "threshold_type": "PERCENTAGE",
572
+ "threshold_value": 90,
573
+ "period_start_time": "2026-05-18T00:00:00Z",
574
+ "period_end_time": null,
575
+ "subscription_id": "137e4652-5540-4a3b-9bce-fa393b028539",
576
+ "organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
577
+ "created_on": "2026-05-18T17:57:16Z",
578
+ "modified_on": "2026-05-18T17:57:17Z"
579
+ }
580
+ }
581
+ }
582
+ ```
583
+
584
+ ```json
585
+ {
586
+ "id": "2f31925f-10fc-41eb-8cb9-3cdf2b4e9e29",
587
+ "type": "invoice.created",
588
+ "created_at": "2026-04-02T05:56:33Z",
589
+ "data": {
590
+ "object": {
591
+ "id": "INV-20260402055633-FCM4B",
592
+ "object": "invoice",
593
+ "status": "OPEN",
594
+ "paid_at": null,
595
+ "amount_total": "40",
596
+ "amount_total_units": 4000,
597
+ "currency": "USD",
598
+ "due_date": null,
599
+ "order_id": null,
600
+ "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
601
+ "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
602
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
603
+ "product": {
604
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
605
+ "name": "ParityDeals"
606
+ },
607
+ "created_on": "2026-04-02T05:56:33Z",
608
+ "modified_on": "2026-04-02T05:56:33Z"
609
+ }
610
+ }
611
+ }
612
+ ```
613
+
614
+ ```json
615
+ {
616
+ "id": "9d2c7e54-3f1b-4a8c-9e6d-2b5f8e1a4c7b",
617
+ "type": "invoice.paid",
618
+ "created_at": "2026-04-02T06:00:00Z",
619
+ "data": {
620
+ "object": {
621
+ "id": "INV-20260402055633-FCM4B",
622
+ "object": "invoice",
623
+ "status": "PAID",
624
+ "paid_at": "2026-04-02T06:00:00Z",
625
+ "amount_total": "40",
626
+ "amount_total_units": 4000,
627
+ "currency": "USD",
628
+ "due_date": null,
629
+ "order_id": null,
630
+ "customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
631
+ "subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
632
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
633
+ "product": {
634
+ "id": "df398021-477b-4e67-972d-c763a2f2ba7b",
635
+ "name": "ParityDeals"
636
+ },
637
+ "created_on": "2026-04-02T05:56:33Z",
638
+ "modified_on": "2026-04-02T06:00:00Z"
639
+ },
640
+ "previous_attributes": {
641
+ "status": "OPEN",
642
+ "paid_at": null
643
+ }
644
+ }
645
+ }
646
+ ```
647
+
648
+ ```json
649
+ {
650
+ "id": "6e76547b-9b6b-4504-af36-c8f646fa91fe",
651
+ "type": "refund.created",
652
+ "created_at": "2026-04-02T05:41:21Z",
653
+ "data": {
654
+ "object": {
655
+ "id": "ca435ba3-d951-472d-a836-370787df3026",
656
+ "object": "refund",
657
+ "status": "PROCESSING",
658
+ "amount": "20.0",
659
+ "amount_units": 2000,
660
+ "currency": "USD",
661
+ "reason": "REQUESTED_BY_CUSTOMER",
662
+ "order_id": "ORD-20260402042513-8M80C",
663
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
664
+ "created_on": "2026-04-02T05:41:21Z",
665
+ "modified_on": "2026-04-02T05:41:21Z"
666
+ }
667
+ }
668
+ }
669
+ ```
670
+
671
+ ```json
672
+ {
673
+ "id": "evt_01HXYZ2345678901BCDEFG",
674
+ "type": "refund.updated",
675
+ "created_at": "2026-04-02T05:41:30Z",
676
+ "data": {
677
+ "object": {
678
+ "id": "ca435ba3-d951-472d-a836-370787df3026",
679
+ "object": "refund",
680
+ "status": "SUCCEEDED",
681
+ "amount": "20.0",
682
+ "amount_units": 2000,
683
+ "currency": "USD",
684
+ "reason": "REQUESTED_BY_CUSTOMER",
685
+ "order_id": "ORD-20260402042513-8M80C",
686
+ "organization": "9b759915-5387-4e61-90e9-2162318e8d17",
687
+ "created_on": "2026-04-02T05:41:21Z",
688
+ "modified_on": "2026-04-02T05:41:30Z"
689
+ },
690
+ "previous_attributes": {
691
+ "status": "PROCESSING"
692
+ }
693
+ }
694
+ }
695
+ ```
696
+
697
+ ---
698
+
699
+ ## Verifying Signatures
700
+
701
+ Always verify the signature before processing a webhook. Skipping verification exposes your endpoint to spoofed requests from third parties.
702
+
703
+ Kelviq signs every request using **HMAC-SHA256**. To verify a request:
704
+
705
+ 1. Read the `webhook-id` and `webhook-timestamp` headers.
706
+ 2. Construct the signed string by concatenating: `{webhook-id}.{webhook-timestamp}.{raw-request-body}` (joined with `.`)
707
+ 3. Compute HMAC-SHA256 over the signed string using your endpoint's signing secret as the key.
708
+ 4. Compare the hex digest to the signature in the `webhook-signature` header (strip the `v1,` prefix before comparing).
709
+ 5. Reject the request if the signatures do not match.
710
+
711
+ 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.
712
+
713
+ Optionally, also check that `webhook-timestamp` is within a few minutes of your server's current time to defend against replay attacks.
714
+
715
+ ---
716
+
717
+ ## Code Examples
718
+
719
+ 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.
720
+
721
+ ```javascript Node.js
722
+ const crypto = require('crypto');
723
+
724
+ function verifyWebhook(req, signingSecret) {
725
+ const webhookId = req.headers['webhook-id'];
726
+ const webhookTimestamp = req.headers['webhook-timestamp'];
727
+ const webhookSignature = req.headers['webhook-signature'];
728
+
729
+ if (!webhookId || !webhookTimestamp || !webhookSignature) {
730
+ throw new Error('Missing required webhook headers');
731
+ }
732
+
733
+ // Defend against replay attacks (5-minute tolerance)
734
+ const now = Math.floor(Date.now() / 1000);
735
+ if (Math.abs(now - parseInt(webhookTimestamp, 10)) > 300) {
736
+ throw new Error('Webhook timestamp is too old');
737
+ }
738
+
739
+ // Reconstruct the signed payload
740
+ const rawBody = req.body; // must be the raw Buffer/string, not parsed JSON
741
+ const signedPayload = `${webhookId}.${webhookTimestamp}.${rawBody}`;
742
+
743
+ // Compute HMAC-SHA256
744
+ const expectedSignature = crypto
745
+ .createHmac('sha256', signingSecret)
746
+ .update(signedPayload, 'utf8')
747
+ .digest('hex');
748
+
749
+ // Strip the "v1," prefix from the header value
750
+ const [, receivedSignature] = webhookSignature.split(',');
751
+
752
+ if (!crypto.timingSafeEqual(
753
+ Buffer.from(expectedSignature, 'hex'),
754
+ Buffer.from(receivedSignature, 'hex')
755
+ )) {
756
+ throw new Error('Webhook signature mismatch');
757
+ }
758
+
759
+ return JSON.parse(rawBody);
760
+ }
761
+
762
+ // Express handler example
763
+ app.post('/webhooks/kelviq', express.raw({ type: 'application/json' }), (req, res) => {
764
+ let event;
765
+ try {
766
+ event = verifyWebhook(req, process.env.KELVIQ_WEBHOOK_SECRET);
767
+ } catch (err) {
768
+ console.error('Webhook verification failed:', err.message);
769
+ return res.status(400).send('Bad Request');
770
+ }
771
+
772
+ switch (event.type) {
773
+ case 'subscription.created':
774
+ console.log('New subscription:', event.data.object.id);
775
+ break;
776
+ case 'invoice.paid':
777
+ console.log('Invoice paid:', event.data.object.id);
778
+ break;
779
+ default:
780
+ console.log('Unhandled event type:', event.type);
781
+ }
782
+
783
+ res.status(200).json({ received: true });
784
+ });
785
+ ```
786
+
787
+ ```python Python
788
+ import hashlib
789
+ import hmac
790
+ import json
791
+ import time
792
+ from flask import Flask, request, abort
793
+
794
+ app = Flask(__name__)
795
+ SIGNING_SECRET = "kq_whsec_your_secret_here" # load from environment
796
+
797
+ def verify_webhook(payload_bytes: bytes, webhook_id: str, webhook_timestamp: str, webhook_signature: str) -> dict:
798
+ # Defend against replay attacks (5-minute tolerance)
799
+ now = int(time.time())
800
+ if abs(now - int(webhook_timestamp)) > 300:
801
+ raise ValueError("Webhook timestamp is too old")
802
+
803
+ # Reconstruct the signed payload (body must be the raw bytes decoded as utf-8)
804
+ signed_payload = f"{webhook_id}.{webhook_timestamp}.{payload_bytes.decode('utf-8')}"
805
+
806
+ # Compute HMAC-SHA256
807
+ expected_signature = hmac.new(
808
+ SIGNING_SECRET.encode("utf-8"),
809
+ signed_payload.encode("utf-8"),
810
+ hashlib.sha256,
811
+ ).hexdigest()
812
+
813
+ # Strip the "v1," prefix from the header value
814
+ _, received_signature = webhook_signature.split(",", 1)
815
+
816
+ if not hmac.compare_digest(expected_signature, received_signature):
817
+ raise ValueError("Webhook signature mismatch")
818
+
819
+ return json.loads(payload_bytes)
820
+
821
+ @app.route("/webhooks/kelviq", methods=["POST"])
822
+ def handle_webhook():
823
+ webhook_id = request.headers.get("webhook-id")
824
+ webhook_timestamp = request.headers.get("webhook-timestamp")
825
+ webhook_signature = request.headers.get("webhook-signature")
826
+
827
+ try:
828
+ event = verify_webhook(request.get_data(), webhook_id, webhook_timestamp, webhook_signature)
829
+ except ValueError as e:
830
+ print(f"Webhook verification failed: {e}")
831
+ abort(400)
832
+
833
+ event_type = event.get("type")
834
+ if event_type == "subscription.created":
835
+ print("New subscription:", event["data"]["object"]["id"])
836
+ elif event_type == "invoice.paid":
837
+ print("Invoice paid:", event["data"]["object"]["id"])
838
+ else:
839
+ print("Unhandled event type:", event_type)
840
+
841
+ return {"received": True}, 200
842
+ ```
843
+
844
+ ```go Go
845
+ package main
846
+
847
+ import (
848
+ "crypto/hmac"
849
+ "crypto/sha256"
850
+ "encoding/hex"
851
+ "encoding/json"
852
+ "errors"
853
+ "fmt"
854
+ "io"
855
+ "math"
856
+ "net/http"
857
+ "strconv"
858
+ "strings"
859
+ "time"
860
+ )
861
+
862
+ const signingSecret = "kq_whsec_your_secret_here" // load from environment
863
+
864
+ type WebhookEvent struct {
865
+ ID string `json:"id"`
866
+ Type string `json:"type"`
867
+ CreatedAt string `json:"created_at"`
868
+ Data json.RawMessage `json:"data"`
869
+ }
870
+
871
+ func verifyWebhook(body []byte, webhookID, webhookTimestamp, webhookSignature string) (*WebhookEvent, error) {
872
+ // Defend against replay attacks (5-minute tolerance)
873
+ ts, err := strconv.ParseInt(webhookTimestamp, 10, 64)
874
+ if err != nil {
875
+ return nil, errors.New("invalid webhook-timestamp header")
876
+ }
877
+ if math.Abs(float64(time.Now().Unix()-ts)) > 300 {
878
+ return nil, errors.New("webhook timestamp is too old")
879
+ }
880
+
881
+ // Reconstruct the signed payload
882
+ signedPayload := fmt.Sprintf("%s.%s.%s", webhookID, webhookTimestamp, string(body))
883
+
884
+ // Compute HMAC-SHA256
885
+ mac := hmac.New(sha256.New, []byte(signingSecret))
886
+ mac.Write([]byte(signedPayload))
887
+ expectedSig := hex.EncodeToString(mac.Sum(nil))
888
+
889
+ // Strip the "v1," prefix from the header value
890
+ parts := strings.SplitN(webhookSignature, ",", 2)
891
+ if len(parts) != 2 {
892
+ return nil, errors.New("malformed webhook-signature header")
893
+ }
894
+ receivedSig := parts[1]
895
+
896
+ expectedBytes, _ := hex.DecodeString(expectedSig)
897
+ receivedBytes, _ := hex.DecodeString(receivedSig)
898
+ if !hmac.Equal(expectedBytes, receivedBytes) {
899
+ return nil, errors.New("webhook signature mismatch")
900
+ }
901
+
902
+ var event WebhookEvent
903
+ if err := json.Unmarshal(body, &event); err != nil {
904
+ return nil, fmt.Errorf("failed to parse webhook body: %w", err)
905
+ }
906
+ return &event, nil
907
+ }
908
+
909
+ func webhookHandler(w http.ResponseWriter, r *http.Request) {
910
+ body, err := io.ReadAll(r.Body)
911
+ if err != nil {
912
+ http.Error(w, "cannot read body", http.StatusBadRequest)
913
+ return
914
+ }
915
+ defer r.Body.Close()
916
+
917
+ event, err := verifyWebhook(
918
+ body,
919
+ r.Header.Get("webhook-id"),
920
+ r.Header.Get("webhook-timestamp"),
921
+ r.Header.Get("webhook-signature"),
922
+ )
923
+ if err != nil {
924
+ http.Error(w, "Bad Request: "+err.Error(), http.StatusBadRequest)
925
+ return
926
+ }
927
+
928
+ switch event.Type {
929
+ case "subscription.created":
930
+ fmt.Println("New subscription:", event.ID)
931
+ case "invoice.paid":
932
+ fmt.Println("Invoice paid:", event.ID)
933
+ default:
934
+ fmt.Println("Unhandled event type:", event.Type)
935
+ }
936
+
937
+ w.Header().Set("Content-Type", "application/json")
938
+ w.WriteHeader(http.StatusOK)
939
+ w.Write([]byte(`{"received":true}`))
940
+ }
941
+
942
+ func main() {
943
+ http.HandleFunc("/webhooks/kelviq", webhookHandler)
944
+ http.ListenAndServe(":8080", nil)
945
+ }
946
+ ```
947
+
948
+ ---
949
+
950
+ ## Best Practices
951
+
952
+ - **Return `2xx` fast.** Acknowledge the webhook immediately and process it asynchronously. Long-running handlers increase the risk of timeouts and duplicate retries.
953
+ - **Make handlers idempotent.** The same event may be delivered more than once. Use `data.id` (the event UUID) as a deduplication key.
954
+ - **Validate the timestamp.** Reject requests where `webhook-timestamp` is more than 5 minutes from your server's clock to prevent replay attacks.
955
+ - **Use `hmac.compare_digest` / `hmac.Equal` / `crypto.timingSafeEqual`.** Constant-time comparison prevents timing side-channel attacks.
956
+ - **Store the raw body before parsing.** Signature verification operates on the raw bytes, not the deserialized object.
957
+
958
+ ---
959
+
960
+ ## Need Help?
961
+
962
+ - Email us at **hi@kelviq.com**
963
+ - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)