Webhook events
The thirteen webhook events a webhook can subscribe to, and the exact body of each.
A webhook subscribes to one or more of these thirteen types. In each envelope, data is the object as the public API returns it: its fields are described in the reference.
| Type | When | data |
|---|---|---|
order.paid | An order is paid, from the catalogue or a payment link. | The order, as GET /v1/orders/{id} |
order.failed | The payment provider confirms that the payment of an order failed. | The order, as GET /v1/orders/{id} |
order.refunded | A paid order is refunded to the buyer. | The order, as GET /v1/orders/{id} |
customer.created | A new customer is recorded in the store (first order or created through the API). | The customer, as GET /v1/customers/{id} |
product.published | A product is published, from the dashboard or the API. | The product, as GET /v1/products/{id} |
product.archived | A product is archived. | The product, as GET /v1/products/{id} |
payment_link.paid | A payment link is paid. | The order, with its paymentLink filled in |
license_key.issued | A license key is given to the buyer. | The key, as in GET /v1/license-keys |
license_key.activated | A device is activated on a license key. | The key, with activation |
license_key.deactivated | A device is freed from a license key. | The key, with activation |
license_key.revoked | A license key is revoked, by you or by a refund. | The key, with reason |
license_key.expiring | A license key expires in seven days or less. | The key, with daysUntilExpiry |
license_key.expired | A license key has just expired. | The key, as in GET /v1/license-keys |
One last type, ping, is only sent by the Envoyer un test (send a test) button; it cannot be subscribed to.
The examples below are the exact bodies Kivoo sends, with example ids.
order.paid
An order is paid. This is the event to listen to for delivering, filling a spreadsheet or telling your team. An order paid through a payment link also triggers payment_link.paid.
The order of a checkout session carries checkout: its id, and the externalReference and metadata your application gave it. An order placed in the store has checkout: null. The example below is a session's (see Accept payments from your app).
{
"id": "a1f0c3d2-6b7e-4f81-9a2c-3d4e5f6a7b80",
"type": "order.paid",
"createdAt": "2026-10-18T09:14:04.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2",
"status": "PAID",
"amount": 4500,
"currency": "XAF",
"platformFeePercent": 10,
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"name": "Awa Diallo",
"email": "awa@example.com",
"phone": "+237655000000"
},
"items": [
{
"id": "0b7c3e5a-1d2f-4a6b-8c9d-0e1f2a3b4c5d",
"productId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"type": "LICENSE",
"title": "Plan Pro — 30 jours",
"unitAmount": 4500,
"quantity": 1
}
],
"paymentLink": null,
"checkout": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"externalReference": "42",
"metadata": {
"plan": "pro",
"workspace": "acme"
}
},
"note": null,
"couponCode": null,
"discountAmount": 0,
"paidAt": "2026-10-18T09:14:03.000Z",
"createdAt": "2026-10-18T09:13:10.000Z"
}
}order.failed
The payment provider confirmed that the payment of the order failed (status: "FAILED"). An order abandoned without an answer from the provider sends nothing.
{
"id": "b2e1d4c3-7c8f-4a92-8b3d-4e5f6a7b8c91",
"type": "order.failed",
"createdAt": "2026-09-12T11:20:02.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "6d5c4b3a-2918-4a7f-8e6d-5c4b3a291807",
"reference": "KV-9M2P4RT7",
"status": "FAILED",
"amount": 5000,
"currency": "XAF",
"platformFeePercent": 10,
"customer": {
"id": "7d9e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
"name": "Aminata Diallo",
"email": "aminata@example.com",
"phone": "+237655000000"
},
"items": [
{
"id": "0b7c3e5a-1d2f-4a6b-8c9d-0e1f2a3b4c5d",
"productId": "3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f",
"type": "FILE",
"title": "Guide du freelance",
"unitAmount": 5000,
"quantity": 1
}
],
"paymentLink": null,
"checkout": null,
"note": null,
"couponCode": null,
"discountAmount": 0,
"paidAt": null,
"createdAt": "2026-09-12T11:18:00.000Z"
}
}order.refunded
A paid order was refunded to the buyer (status: "REFUNDED"): the store owner asked for it within 48 hours of the payment, Kivoo approved it, and the transfer to the number that paid is confirmed. The buyer gets the total minus the Kivoo commission. A request cancelled, refused or whose transfer fails sends nothing: the order stays paid.
{
"id": "c3f2e1d0-8a9b-4c7d-9e6f-5a4b3c2d1e0f",
"type": "order.refunded",
"createdAt": "2026-09-13T09:42:10.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "5c4b3a29-1807-4f6e-9d5c-4b3a29180706",
"reference": "KV-7F3K9QA2",
"status": "REFUNDED",
"amount": 5000,
"currency": "XAF",
"platformFeePercent": 10,
"customer": {
"id": "7d9e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
"name": "Aminata Diallo",
"email": "aminata@example.com",
"phone": "+237655000000"
},
"items": [
{
"id": "0b7c3e5a-1d2f-4a6b-8c9d-0e1f2a3b4c5d",
"productId": "3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f",
"type": "FILE",
"title": "Guide du freelance",
"unitAmount": 5000,
"quantity": 1
}
],
"paymentLink": null,
"checkout": null,
"note": null,
"couponCode": null,
"discountAmount": 0,
"paidAt": "2026-09-12T10:05:00.000Z",
"createdAt": "2026-09-12T10:03:00.000Z"
}
}customer.created
A new customer is recorded in the store: when they place their first order, before it is paid (an order that then fails has still created them), or when created through the API. A customer the store already knows sends nothing.
{
"id": "c3d2e5f4-8d9a-4ba3-9c4e-5f6a7b8c9da2",
"type": "customer.created",
"createdAt": "2026-09-12T10:03:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "7d9e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
"name": "Aminata Diallo",
"email": "aminata@example.com",
"phone": "+237655000000",
"ordersCount": 0,
"totalPaid": 0,
"currency": "XAF",
"createdAt": "2026-09-12T10:03:00.000Z"
}
}product.published
A product moves to the PUBLISHED status, from the dashboard or the API. A change that leaves the status as it was sends nothing.
{
"id": "d4c3f6a5-9eab-4cb4-8d5f-6a7b8c9daeb3",
"type": "product.published",
"createdAt": "2026-09-01T08:00:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f",
"title": "Guide du freelance",
"slug": "guide-du-freelance-a3f9k2p1",
"type": "FILE",
"status": "PUBLISHED",
"summary": "Trouver ses premiers clients en trente jours.",
"description": "<p>Un guide pas à pas.</p>",
"priceAmount": 5000,
"compareAtAmount": 7500,
"pricing": "FIXED",
"maxPriceAmount": null,
"currency": "XAF",
"url": "https://atelier-nour.kivoo.co/guide-du-freelance-a3f9k2p1",
"imageUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/image?v=image.jpg",
"coverImageUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/cover-image?v=cover.jpg",
"publishedAt": "2026-09-01T08:00:00.000Z",
"createdAt": "2026-08-28T15:12:00.000Z",
"updatedAt": "2026-09-01T08:00:00.000Z",
"license": null
}
}product.archived
A product moves to the ARCHIVED status: archived from the dashboard or the API, or deleted while it already has orders, in which case Kivoo archives it instead of deleting it. A product deleted for good, or moved back to draft, sends nothing.
{
"id": "e5b4a7b6-afbc-4dc5-9e6a-7b8c9daebfc4",
"type": "product.archived",
"createdAt": "2026-09-20T16:45:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f",
"title": "Guide du freelance",
"slug": "guide-du-freelance-a3f9k2p1",
"type": "FILE",
"status": "ARCHIVED",
"summary": "Trouver ses premiers clients en trente jours.",
"description": "<p>Un guide pas à pas.</p>",
"priceAmount": 5000,
"compareAtAmount": 7500,
"pricing": "FIXED",
"maxPriceAmount": null,
"currency": "XAF",
"url": null,
"imageUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/image?v=image.jpg",
"coverImageUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/cover-image?v=cover.jpg",
"publishedAt": "2026-09-01T08:00:00.000Z",
"createdAt": "2026-08-28T15:12:00.000Z",
"updatedAt": "2026-09-20T16:45:00.000Z",
"license": null
}
}payment_link.paid
A payment link is paid. data is the order created by that payment, with its paymentLink (id, code, title). The order.paid event of the same order is sent too.
{
"id": "f6a5b8c7-b0cd-4ed6-8f7b-8c9daebfc0d5",
"type": "payment_link.paid",
"createdAt": "2026-09-14T09:12:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "8f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918",
"reference": "KV-4H8J2LN6",
"status": "PAID",
"amount": 15000,
"currency": "XAF",
"platformFeePercent": 10,
"customer": {
"id": "7d9e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
"name": "Aminata Diallo",
"email": "aminata@example.com",
"phone": "+237655000000"
},
"items": [
{
"id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
"productId": null,
"type": null,
"title": "Acompte robe bleue",
"unitAmount": 15000,
"quantity": 1
}
],
"paymentLink": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"code": "ab23cd45",
"title": "Acompte robe bleue"
},
"checkout": null,
"note": "Taille M, s’il te plaît.",
"couponCode": null,
"discountAmount": 0,
"paidAt": "2026-09-14T09:12:00.000Z",
"createdAt": "2026-09-14T09:10:00.000Z"
}
}license_key.issued
A license key is given to the buyer, when their order is paid (after order.paid). data is the key as the list GET /v1/license-keys returns it: its keyHint, never the full key, which Kivoo writes in no webhook. To read the value, call GET /v1/license-keys/{id}. See Check a license key.
A key sold by a checkout session carries checkout, as in the example below: this is the event that activates the account of your user, with expiresAt (see Accept payments from your app).
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"type": "license_key.issued",
"createdAt": "2026-10-18T09:14:05.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "K7M2-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-18T09:14:03.000Z",
"expiresAt": "2026-11-17T09:14:03.000Z",
"revokedAt": null,
"activations": {
"count": 0,
"max": 1,
"remaining": 1
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Plan Pro — 30 jours"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"externalReference": "42",
"metadata": {
"plan": "pro",
"workspace": "acme"
}
}
}
}license_key.activated
A device takes a place on a key, through POST /v1/license-keys/activate. activation says which one (deviceIdentifier) and when (at). The same device activated a second time sends nothing.
{
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6f",
"type": "license_key.activated",
"createdAt": "2026-10-15T09:20:00.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "BAU-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": null,
"activations": {
"count": 1,
"max": 1,
"remaining": 0
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Bauhaus Pro"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": null,
"activation": {
"deviceIdentifier": "mac-7f3a9c",
"at": "2026-10-15T09:20:00.000Z"
}
}
}license_key.deactivated
A device frees its place on a key, through POST /v1/license-keys/deactivate or from the dashboard. activation says which one and when.
{
"id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"type": "license_key.deactivated",
"createdAt": "2026-10-28T17:05:00.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "BAU-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": null,
"activations": {
"count": 0,
"max": 1,
"remaining": 1
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Bauhaus Pro"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": null,
"activation": {
"deviceIdentifier": "mac-7f3a9c",
"at": "2026-10-28T17:05:00.000Z"
}
}
}license_key.revoked
A key is revoked, for good: by you, with POST /v1/license-keys/{id}/revoke or from the dashboard, and reason carries your text (null without one); or because its order was refunded, and reason is refund, right after order.refunded. Cut the access at once, without waiting for your cache to run out.
{
"id": "4d5e6f7a-8b9c-4dae-9f0a-2b3c4d5e6f7a",
"type": "license_key.revoked",
"createdAt": "2026-10-16T14:30:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "BAU-…-Q4RT",
"status": "revoked",
"isActive": false,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": "2026-10-16T14:30:00.000Z",
"activations": {
"count": 1,
"max": 1,
"remaining": 0
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Bauhaus Pro"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": null,
"reason": "refund"
}
}license_key.expiring
A key expires in seven days or less. Kivoo checks daily at 06:00 UTC and sends the event once per key; daysUntilExpiry says how many days it has left, rounded up. The buyer of a key bought in the store gets an e-mail at the same time, inviting them to buy the license again; a key sold through a checkout session gets none, reminding the user is up to your app. A permanent, revoked or refunded key sends nothing, nor does a key already renewed by a session for the same externalReference.
{
"id": "5e6f7a8b-9c0d-4ebf-8a1b-3c4d5e6f7a8b",
"type": "license_key.expiring",
"createdAt": "2026-11-08T06:00:02.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "BAU-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": null,
"activations": {
"count": 1,
"max": 1,
"remaining": 0
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Bauhaus Pro"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": null,
"daysUntilExpiry": 7
}
}license_key.expired
A key’s expiry date has passed (status: "expired"). Kivoo checks every hour: the event arrives within the hour after the end, once per key. A revoked or refunded key sends nothing, nor does a key already renewed by a checkout session. Buying the license again in the store gives a new key.
{
"id": "6f7a8b9c-0d1e-4fca-9b2c-4d5e6f7a8b9c",
"type": "license_key.expired",
"createdAt": "2026-11-14T10:00:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "BAU-…-Q4RT",
"status": "expired",
"isActive": false,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": null,
"activations": {
"count": 1,
"max": 1,
"remaining": 0
},
"product": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"title": "Bauhaus Pro"
},
"customer": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "awa@example.com"
},
"order": {
"id": "4d5e6f7a-8b9c-4d0e-8f2a-3b4c5d6e7f8a",
"reference": "KV-7F3K9QA2"
},
"checkout": null
}
}ping
The test event, sent by the Envoyer un test button of the webhook’s page.
{
"id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"type": "ping",
"createdAt": "2026-09-26T10:00:00.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"message": "Kivoo webhook test",
"sentAt": "2026-09-26T10:00:00.000Z"
}
}