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 :

  1. URL : l’adresse qui recevra les événements, en https://, 2 048 caractères au plus. 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, un mot de passe ou un fragment (#…).
  2. Description (facultative, 120 caractères au plus) : à quoi sert ce webhook.
  3. Événements : les événements webhook à recevoir ; les treize 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. Le bouton sert au plus dix fois par minute et par boutique (429 rate_limited au-delà), et pas sur un webhook désactivé (409 webhook_disabled) :

ping
{
  "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 :

ChampContenu
idL’identifiant de l’événement webhook (UUID), le même à chaque tentative.
typeLe type d’événement, par exemple order.paid.
createdAtLa date de l’événement, ISO 8601 en UTC.
storeLa boutique : id et slug.
dataL’objet concerné, exactement tel que l’API publique le renvoie (la commande de GET /v1/orders/{id}…).

Et ces en-têtes :

En-têteContenu
Content-Typeapplication/json
User-AgentKivoo-Webhooks/1.0
Kivoo-Signaturet=<horodatage>,v1=<signature> : voir Vérifier la signature.
Kivoo-Event-IdL’id de l’événement, stable d’une tentative à l’autre : ta clé d’idempotence.
Kivoo-Event-TypeLe type de l’événement.
Kivoo-Delivery-AttemptLe 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 d’une réponse 2xx n’est pas lu ; celui d’une autre réponse est gardé dans le journal, tronqué (voir Tentatives et journal).
  • 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 3xx est un échec. Donne l’adresse finale.
  • Un échec est retenté plusieurs fois, sur près d’une journée : voir Tentatives et journal.

Quand Kivoo n’envoie rien

  • Une boutique suspendue, ou fermée parce que son propriétaire a supprimé son compte, n’envoie plus d’événement : ses livraisons en attente s’arrêtent avec l’erreur store_unavailable, et on ne peut plus lui ajouter de webhook. Ses clés API sont aussi refusées (403 store_unavailable).
  • Un webhook désactivé, par toi ou automatiquement, ne reçoit rien, et ne reçoit pas plus tard ce qui s’est passé pendant ce temps.
  • Un type d’événement auquel le webhook n’est pas abonné n’est pas envoyé. Un type ajouté par Kivoo après la création du webhook n’est pas coché d’office : ouvre la fiche du webhook pour l’ajouter.

Sur cette page