Recevoir les webhooks
Un webhook est une adresse de votre serveur que KiwiDesk appelle (requête POST en JSON) à
chaque fois qu’un événement choisi se produit : un ticket est créé, un appareil est prêt, une
facture est émise, un stock passe sous son seuil… Votre outil est prévenu tout de suite, sans
interroger l’API en boucle.
Chaque envoi est signé (HMAC-SHA256) pour que vous sachiez qu’il vient bien de KiwiDesk, et renvoyé automatiquement si votre serveur ne répond pas.
Créer un webhook
Section intitulée « Créer un webhook »Il faut la permission « Gérer les webhooks » (core:webhooks:manage).
- Ouvrez Paramètres > API & Webhooks (groupe Avancé), onglet Webhooks.
- Cliquez sur Nouveau webhook.
- Donnez un Nom, choisissez la Boutique dont vous voulez les événements (Toutes les
boutiques est réservé aux super administrateurs) et saisissez l’URL de votre serveur, de
préférence en
https://. - Cochez les événements à recevoir. Le catalogue des événements décrit le contenu de chacun.
- Laissez Actif coché et cliquez sur Enregistrer.
- Copiez le Secret de signature (
whsec_...) affiché : il ne sera plus jamais montré. Rangez-le dans la configuration de votre serveur.


Les mêmes opérations existent dans l’API (GET|POST /api/webhooks, PATCH|DELETE /api/webhooks/{id}, POST /api/webhooks/{id}/rotate-secret), réservées à une session
utilisateur. GET /api/webhooks/events renvoie la liste des événements disponibles, les en-têtes
et la formule de signature.
Un webhook lié à une boutique ne reçoit que les événements de cette boutique. Un webhook « Toutes
les boutiques » reçoit aussi les événements de l’instance entière (storeId: null). Les webhooks
des plugins se gèrent dans Paramètres > Plugins et n’apparaissent pas dans cette liste.
Ce que KiwiDesk envoie
Section intitulée « Ce que KiwiDesk envoie »POST /kiwidesk/webhooks HTTP/1.1Content-Type: application/jsonUser-Agent: KiwiDesk-Webhooks/0.1X-KiwiDesk-Event: repair.ticket.status_changedX-KiwiDesk-Event-Id: 01a1f6a2-3c4d-7e5f-8a9b-0c1d2e3f4a5bX-KiwiDesk-Timestamp: 1795129200X-KiwiDesk-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
{"id":"01a1f6a2-3c4d-7e5f-8a9b-0c1d2e3f4a5b","name":"repair.ticket.status_changed","occurredAt":"2026-11-20T08:20:00.000Z","storeId":"01a1bafb-6510-738f-98da-85c97912cce8","actor":{"userId":"01a1bafb-5d70-76d8-9d73-7b5aa8a4e504","apiKeyId":null,"ipAddress":"192.0.2.10"},"payload":{"ticketId":"01a1f66e-8ee0-71d2-92fb-a88b1629ab6a","ticketNumber":"REP-2026-0215","customerId":"01a1f66d-f0ce-7051-8be1-2b9967d3e9b2","fromStatus":"IN_REPAIR","toStatus":"READY_FOR_PICKUP","comment":null}}| En-tête | Contenu |
|---|---|
X-KiwiDesk-Event |
Nom de l’événement |
X-KiwiDesk-Event-Id |
Identifiant unique de l’événement, le même à chaque nouvelle tentative : votre clé d’idempotence |
X-KiwiDesk-Timestamp |
Heure de l’envoi, en secondes Unix (change à chaque tentative) |
X-KiwiDesk-Signature |
sha256= suivi du HMAC-SHA256 en hexadécimal |
Le corps est toujours une enveloppe :
| Champ | Contenu |
|---|---|
id |
Identifiant de l’événement (UUID v7), identique à X-KiwiDesk-Event-Id |
name |
Nom de l’événement |
occurredAt |
Date de l’événement (ISO 8601, UTC), pas celle de l’envoi |
storeId |
Boutique concernée, null pour un événement de toute l’instance |
actor |
Qui l’a déclenché : userId (session), apiKeyId (clé API), ou les deux null (KiwiDesk lui-même, tâche planifiée) ; ipAddress |
payload |
Les données propres à l’événement, décrites dans le catalogue |
Le contenu est volontairement court (identifiants, numéros, montants) : pour le détail, appelez
l’API avec l’identifiant reçu (GET /api/repair/tickets/{ticketId}).
Vérifier la signature
Section intitulée « Vérifier la signature »La signature est le HMAC-SHA256, avec le secret du webhook, du texte
<X-KiwiDesk-Timestamp>.<corps brut> (l’horodatage, un point, puis le corps exactement tel que
reçu). Pour l’accepter :
- recalculez-la sur le corps brut, avant tout décodage JSON (un JSON relu puis réécrit ne donne pas les mêmes octets) ;
- comparez-la à
X-KiwiDesk-Signatureen temps constant ; - refusez un horodatage écarté de plus de 5 minutes de votre horloge : un envoi intercepté ne peut pas être rejoué plus tard.
Répondez 401 à un envoi qui ne passe pas ces contrôles.
import { createHmac, timingSafeEqual } from "node:crypto";
/** True when the delivery comes from KiwiDesk. rawBody: the body as received (string). */export function verifyKiwiDeskSignature(secret, rawBody, timestampHeader, signatureHeader) { if (!/^\d+$/.test(timestampHeader ?? "") || !signatureHeader) { return false; } const timestamp = Number(timestampHeader); if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) { return false; } const expected = Buffer.from( "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`, "utf8").digest("hex"), ); const received = Buffer.from(signatureHeader); return expected.length === received.length && timingSafeEqual(expected, received);}Avec Express, gardez le corps brut : app.post("/kiwidesk/webhooks", express.raw({ type: "application/json" }), handler) puis req.body.toString("utf8"). Un exemple complet sans
dépendance est dans examples/webhooks/receiver-node.
import hashlibimport hmacimport time
def verify_kiwidesk_signature(secret: str, raw_body: bytes, timestamp: str | None, signature: str | None) -> bool: """True when the delivery comes from KiwiDesk. raw_body: the bytes as received.""" if not timestamp or not signature or not timestamp.isdigit(): return False if abs(int(time.time()) - int(timestamp)) > 300: return False signed = f"{timestamp}.".encode() + raw_body expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)Avec Flask : verify_kiwidesk_signature(secret, request.get_data(), request.headers.get("X-KiwiDesk-Timestamp"), request.headers.get("X-KiwiDesk-Signature")).
Un exemple complet avec la seule bibliothèque standard est dans
examples/webhooks/receiver-python.
<?phpfunction verify_kiwidesk_signature(string $secret, string $rawBody, ?string $timestamp, ?string $signature): bool{ if ($timestamp === null || $signature === null || !ctype_digit($timestamp)) { return false; } if (abs(time() - (int) $timestamp) > 300) { return false; } $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); return hash_equals($expected, $signature);}
$rawBody = file_get_contents('php://input');$valid = verify_kiwidesk_signature( getenv('KIWIDESK_WEBHOOK_SECRET'), $rawBody, $_SERVER['HTTP_X_KIWIDESK_TIMESTAMP'] ?? null, $_SERVER['HTTP_X_KIWIDESK_SIGNATURE'] ?? null);if (!$valid) { http_response_code(401); exit;}$event = json_decode($rawBody, true);Répondre, et ce qui se passe en cas d’échec
Section intitulée « Répondre, et ce qui se passe en cas d’échec »- Répondez par un statut 2xx dans les 10 secondes : l’envoi est alors Réussi. Faites le travail long après avoir répondu (file d’attente, tâche de fond).
- Tout autre statut, un délai dépassé, une erreur réseau ou une redirection (jamais suivie) compte comme un échec.
- Après un échec, KiwiDesk réessaie après 30 secondes, 2 minutes, 10 minutes, 30 minutes, 2 heures puis 6 heures : 7 tentatives en tout, sur environ 9 heures. Les envois sont examinés toutes les 15 secondes.
- Après la septième tentative, l’envoi passe en Échec. Au bout de 10 envois en échec d’affilée, le webhook est désactivé automatiquement (statut Désactivé (échecs)). Un envoi réussi remet ce compteur à zéro ; réactiver le webhook aussi.
- L’ordre d’arrivée n’est pas garanti : fiez-vous à
occurredAt, et à l’API pour l’état actuel.
Le journal des envois
Section intitulée « Le journal des envois »Cliquez sur un webhook dans la liste pour ouvrir son Historique des envois : pour chaque événement, le statut (En attente, Réussi, Échec), le numéro de tentative, le code HTTP reçu, l’erreur, la durée et la prochaine tentative. Le corps de votre réponse est gardé (2 Ko au plus) seulement pour les envois réussis.
Après avoir réparé votre serveur, l’icône Renvoyer d’une ligne reprogramme un envoi tout de suite, avec le même
événement (même identifiant, même contenu, nouvel horodatage et nouvelle signature). Par l’API :
GET /api/webhooks/{id}/deliveries et POST /api/webhooks/{id}/deliveries/{deliveryId}/redeliver.
Changer le secret
Section intitulée « Changer le secret »Dans le menu … de la ligne du webhook, Régénérer le secret crée un nouveau secret, affiché une fois. L’ancien cesse aussitôt de signer : mettez à jour votre serveur dans la foulée (les envois refusés entre-temps seront retentés).
Être idempotent
Section intitulée « Être idempotent »Un même événement peut vous arriver plusieurs fois : votre serveur a traité l’envoi mais sa réponse s’est perdue, ou quelqu’un a cliqué sur Renvoyer. Votre traitement doit donc supporter la répétition :
- lisez
X-KiwiDesk-Event-Id(ouiddans le corps) ; - si cet identifiant est déjà enregistré comme traité, répondez
200sans rien refaire ; - sinon, traitez l’événement, enregistrez l’identifiant (en base, avec une contrainte d’unicité),
puis répondez
200.
Si le traitement échoue, n’enregistrez pas l’identifiant et répondez 500 : KiwiDesk réessaiera.
Les exemples Node.js et Python du dépôt appliquent exactement cette règle.
Tester en local
Section intitulée « Tester en local »KiwiDesk refuse d’appeler une adresse locale ou privée (localhost, 127.0.0.1,
192.168.x.x, 10.x.x.x, 172.16-31.x.x, adresses de lien local et de métadonnées cloud) : un
utilisateur malveillant ne peut pas s’en servir pour atteindre le réseau interne (protection
SSRF). L’adresse est vérifiée à la création, puis de nouveau à chaque envoi après résolution DNS.
Sinon, la création répond :
{ "statusCode": 400, "code": "BAD_REQUEST", "message": "Un webhook ne peut pas viser une adresse locale ou d'un réseau privé (exceptions : variable WEBHOOK_ALLOWED_PRIVATE_TARGETS)", "details": { "reason": "NON_PUBLIC" }}Trois façons de tester quand même :
Exposez votre serveur de test par un tunnel HTTPS (Cloudflare Tunnel, ngrok…) :
cloudflared tunnel --url http://localhost:4600# ou : ngrok http 4600Utilisez l’adresse https://... donnée par l’outil comme URL du webhook. Rien à changer côté
KiwiDesk, et c’est le chemin le plus proche de la production.
Sur une instance de développement que vous administrez, autorisez le récepteur dans le
fichier .env puis redémarrez l’API :
WEBHOOK_ALLOWED_PRIVATE_TARGETS=192.168.1.20,n8n.lanLa variable accepte des noms d’hôte, des adresses IP et des plages CIDR (192.168.1.0/24),
séparés par des virgules. Avec Docker, localhost désigne le conteneur de l’API lui-même : visez
l’adresse de la machine sur le réseau local, ou host.docker.internal (Docker Desktop) en
l’ajoutant à la variable. En production, ne mettez ici que des serveurs de confiance (par exemple
un n8n sur le réseau de la boutique).
Les deux exemples du dépôt contiennent un script qui envoie un événement signé exactement comme KiwiDesk (mêmes en-têtes, même signature) :
cd examples/webhooks/receiver-nodeKIWIDESK_WEBHOOK_SECRET=whsec_test node src/server.ts# dans un autre terminal :KIWIDESK_WEBHOOK_SECRET=whsec_test node src/send-test-event.tsPratique pour écrire votre traitement avant de brancher la vraie instance.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »| Symptôme | Cause et solution |
|---|---|
| La création répond « adresse locale ou d’un réseau privé » | Voir Tester en local |
| « L’adresse du webhook ne peut pas être résolue » | Le nom d’hôte n’existe pas dans le DNS vu par le serveur KiwiDesk |
Envois en Échec avec HTTP 401 |
Votre vérification refuse la signature : corps relu au lieu du corps brut, mauvais secret, ou horloge du serveur décalée (vérifiez NTP) |
| Envois en Échec avec un délai dépassé | Votre serveur met plus de 10 secondes : répondez d’abord, traitez ensuite |
Envois en échec avec HTTP 301 ou 302 |
Les redirections ne sont pas suivies : mettez l’adresse finale (souvent https://) |
| Le webhook est Désactivé (échecs) | 10 envois en échec d’affilée : réparez le récepteur, réactivez le webhook, puis Renvoyer les envois utiles |
| Aucun envoi pour un événement attendu | Événement non coché, ou webhook lié à une autre boutique que celle de l’événement |