Webhooks
Webhook events
The six webhook events a webhook can subscribe to, and the exact body of each.
A webhook subscribes to one or more of these six 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} |
customer.created | A new customer is recorded in the store (first purchase 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 |
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.
{
"id": "a1f0c3d2-6b7e-4f81-9a2c-3d4e5f6a7b80",
"type": "order.paid",
"createdAt": "2026-09-12T10:05:01.000Z",
"store": {
"id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
"slug": "atelier-nour"
},
"data": {
"id": "5c4b3a29-1807-4f6e-9d5c-4b3a29180706",
"reference": "KV-7F3K9QA2",
"status": "PAID",
"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,
"note": null,
"paidAt": "2026-09-12T10:05:00.000Z",
"createdAt": "2026-09-12T10:03:00.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,
"note": null,
"paidAt": null,
"createdAt": "2026-09-12T11:18:00.000Z"
}
}customer.created
A new customer is recorded in the store: at their first purchase, 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,
"currency": "XAF",
"url": "https://atelier-nour.kivoo.store/guide-du-freelance-a3f9k2p1",
"coverUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/cover?v=cover.jpg",
"publishedAt": "2026-09-01T08:00:00.000Z",
"createdAt": "2026-08-28T15:12:00.000Z",
"updatedAt": "2026-09-01T08:00:00.000Z"
}
}product.archived
A product moves to the ARCHIVED status.
{
"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,
"currency": "XAF",
"url": "https://atelier-nour.kivoo.store/guide-du-freelance-a3f9k2p1",
"coverUrl": "https://api.kivoo.africa/api/v1/products/3a6c2f1e-8b4d-4c1a-9e2f-5d7b8a9c0e1f/cover?v=cover.jpg",
"publishedAt": "2026-09-01T08:00:00.000Z",
"createdAt": "2026-08-28T15:12:00.000Z",
"updatedAt": "2026-09-20T16:45:00.000Z"
}
}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": [],
"paymentLink": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"code": "ab23cd45",
"title": "Acompte robe bleue"
},
"note": "Taille M, s’il te plaît.",
"paidAt": "2026-09-14T09:12:00.000Z",
"createdAt": "2026-09-14T09:10:00.000Z"
}
}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"
}
}