Aller au contenu

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.

Il faut la permission « Gérer les webhooks » (core:webhooks:manage).

  1. Ouvrez Paramètres > API & Webhooks (groupe Avancé), onglet Webhooks.
  2. Cliquez sur Nouveau webhook.
  3. 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://.
  4. Cochez les événements à recevoir. Le catalogue des événements décrit le contenu de chacun.
  5. Laissez Actif coché et cliquez sur Enregistrer.
  6. Copiez le Secret de signature (whsec_...) affiché : il ne sera plus jamais montré. Rangez-le dans la configuration de votre serveur.
Fenêtre Nouveau webhook : champs Nom, Boutique et URL, liste des événements à cocher avec leur description, case Actif et rappel du schéma de signature.
La fenêtre Nouveau webhook ; le bas rappelle comment la signature est calculée.
Onglet Webhooks de Paramètres, API & Webhooks : tableau des webhooks avec nom, URL, événements, dernier envoi et statut, ici vide.
L’onglet Webhooks, avant la création du premier webhook.

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.

POST /kiwidesk/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: KiwiDesk-Webhooks/0.1
X-KiwiDesk-Event: repair.ticket.status_changed
X-KiwiDesk-Event-Id: 01a1f6a2-3c4d-7e5f-8a9b-0c1d2e3f4a5b
X-KiwiDesk-Timestamp: 1795129200
X-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}).

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 :

  1. recalculez-la sur le corps brut, avant tout décodage JSON (un JSON relu puis réécrit ne donne pas les mêmes octets) ;
  2. comparez-la à X-KiwiDesk-Signature en temps constant ;
  3. 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.

  • 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.

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.

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).

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 :

  1. lisez X-KiwiDesk-Event-Id (ou id dans le corps) ;
  2. si cet identifiant est déjà enregistré comme traité, répondez 200 sans rien refaire ;
  3. 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.

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…) :

Fenêtre de terminal
cloudflared tunnel --url http://localhost:4600
# ou : ngrok http 4600

Utilisez 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.

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