Create Webhook Endpoint
POST
/v1/stores/{storeId}/webhooksCoreRegister a webhook endpoint for a store. The signing secret is returned once. Kvell signs every delivery as X-Kvell-Signature: sha256=<hex HMAC-SHA256 over the raw body using this secret>.
Authentication
Signature Pattern
Dashboard JWT bearer (not the HMAC public API).| Header | Value | Description |
|---|---|---|
Authorization | Bearer {jwt} | Merchant dashboard JWT (from /v1/auth/login) |
Content-Type | application/json | Request content type |
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Required | HTTPS URL to deliver events to |
eventTypes | array | Optional | Event types to receive (e.g. ["payment.captured"]) |
Request Example
JSONRequest Body
{
"url": "https://merchant.example.com/kvell/webhook",
"eventTypes": [
"payment.captured",
"payment.refunded",
"payout.succeeded"
]
}Response Parameters
| Field | Type | Example |
|---|---|---|
id | string | "whe_9a2e6b4d4e8a" |
merchantId | string | "mrc_8a1b2c3d4e5f" |
url | string | "https://merchant.example.com/kvell/webhook" |
secret | string | "whsec_2b3c4d5e6f708192a3b4c5d6" |
eventTypes | array | ["payment.captured","payment.refunded","p… |
active | boolean | true |
status | string | "active" |
createdAt | string | "2026-04-13T10:00:00Z" |
Response Example
JSONResponse
{
"id": "whe_9a2e6b4d4e8a",
"merchantId": "mrc_8a1b2c3d4e5f",
"url": "https://merchant.example.com/kvell/webhook",
"secret": "whsec_2b3c4d5e6f708192a3b4c5d6",
"eventTypes": [
"payment.captured",
"payment.refunded",
"payout.succeeded"
],
"active": true,
"status": "active",
"createdAt": "2026-04-13T10:00:00Z"
}Status Codes
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
429Rate Limited
Try itMock
POSThttps://api.pay.sandbox.kvell.group