@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.
- package/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- 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)
|