Événements webhook
Les six événements webhook auxquels un webhook peut s’abonner, et le corps exact de chacun.
Un webhook s’abonne à un ou plusieurs de ces six types. Dans chaque enveloppe, data est l’objet tel que l’API publique le renvoie : les champs sont décrits dans la référence.
| Type | Quand | data |
|---|---|---|
order.paid | Une commande est payée, depuis le catalogue ou un lien de paiement. | La commande, comme GET /v1/orders/{id} |
order.failed | Le fournisseur de paiement confirme l’échec du paiement d’une commande. | La commande, comme GET /v1/orders/{id} |
customer.created | Un nouvel acheteur est enregistré dans la boutique (premier achat ou création par l’API). | L’acheteur, comme GET /v1/customers/{id} |
product.published | Un produit est publié, depuis le dashboard ou l’API. | Le produit, comme GET /v1/products/{id} |
product.archived | Un produit est archivé. | Le produit, comme GET /v1/products/{id} |
payment_link.paid | Un lien de paiement est payé. | La commande, avec son paymentLink renseigné |
Un dernier type, ping, n’est envoyé que par le bouton Envoyer un test ; on ne s’y abonne pas.
Les exemples ci-dessous sont les corps exacts que Kivoo envoie, avec des identifiants d’exemple.
order.paid
Une commande est payée. C’est l’événement à écouter pour livrer, remplir un tableur ou prévenir ton équipe. Une commande payée par un lien de paiement déclenche aussi 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
Le fournisseur de paiement a confirmé que le paiement de la commande a échoué (status: "FAILED"). Une commande abandonnée sans réponse du fournisseur n’envoie rien.
{
"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
Un nouvel acheteur est enregistré dans la boutique : à son premier achat, ou quand il est créé par l’API. Un acheteur déjà connu n’envoie rien.
{
"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
Un produit passe au statut PUBLISHED, depuis le dashboard ou l’API. Une modification qui ne change pas le statut n’envoie rien.
{
"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
Un produit passe au statut ARCHIVED.
{
"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
Un lien de paiement est payé. data est la commande créée par ce paiement, avec son paymentLink (id, code, title). L’événement order.paid de la même commande est envoyé aussi.
{
"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
L’événement de test, envoyé par le bouton Envoyer un test de la fiche du webhook.
{
"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"
}
}