Webhooks
Reçois les événements de ta boutique sur ton serveur, en direct, signés par Kivoo.
Un webhook est une adresse HTTPS de ton serveur à laquelle Kivoo envoie, par une requête POST, les événements webhook de ta boutique : une commande payée, un nouvel acheteur, un produit publié. Plus besoin d’interroger l’API en boucle : ton serveur est prévenu dès que ça se passe.
Les webhooks sont indépendants des clés API : un webhook n’a pas besoin de clé, et une clé révoquée ne coupe aucun webhook.
Ajouter un webhook
Dans le dashboard, ouvre ta boutique puis Paramètres › Développeur › Webhooks et clique sur Ajouter un webhook :
- URL : l’adresse qui recevra les événements, en
https://. Une adresse privée ou locale (localhost,127.0.0.1,10.x.x.x,192.168.x.x…) est refusée, comme une URL qui contient un identifiant ou un mot de passe. - Description (facultative) : à quoi sert ce webhook.
- Événements : les événements webhook à recevoir ; les six sont cochés par défaut.
Une boutique a au plus cinq webhooks. Le propriétaire et les membres Admin les gèrent : modifier, désactiver, réactiver, supprimer.
Le secret de signature
À la création, Kivoo affiche le secret de signature du webhook, qui commence par whsec_. Comme une clé API, il n’est montré qu’une fois : range-le sur ton serveur. Il sert à vérifier que chaque requête vient bien de Kivoo, voir Vérifier la signature.
Régénérer le secret, depuis la fiche du webhook, en affiche un nouveau ; l’ancien cesse aussitôt de signer.
Envoyer un test
Le bouton Envoyer un test de la fiche du webhook envoie un événement ping, signé comme les autres, pour vérifier que ton serveur répond :
{
"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" }
}Ce que Kivoo envoie
Chaque livraison est une requête POST dont le corps JSON est l’enveloppe de l’événement :
| Champ | Contenu |
|---|---|
id | L’identifiant de l’événement webhook (UUID), le même à chaque tentative. |
type | Le type d’événement, par exemple order.paid. |
createdAt | La date de l’événement, ISO 8601 en UTC. |
store | La boutique : id et slug. |
data | L’objet concerné, exactement tel que l’API publique le renvoie (la commande de GET /v1/orders/{id}…). |
Et ces en-têtes :
| En-tête | Contenu |
|---|---|
Content-Type | application/json |
User-Agent | Kivoo-Webhooks/1.0 |
Kivoo-Signature | t=<horodatage>,v1=<signature> : voir Vérifier la signature. |
Kivoo-Event-Id | L’id de l’événement, stable d’une tentative à l’autre : ta clé d’idempotence. |
Kivoo-Event-Type | Le type de l’événement. |
Kivoo-Delivery-Attempt | Le numéro de la tentative, de 1 à 8. |
Répondre à Kivoo
- Réponds par un statut 2xx en moins de 10 secondes : c’est ce qui compte comme une livraison réussie. Le corps de ta réponse n’est pas lu.
- Fais le travail long (envoyer un e-mail, appeler un autre service) après avoir répondu, dans une file de tâches par exemple.
- Kivoo ne suit pas les redirections : une réponse
3xxest un échec. Donne l’adresse finale. - Un échec est retenté plusieurs fois, sur près d’une journée : voir Tentatives et journal.