Article 9 sur 9
Recevoir les événements de vos montres (webhooks)
Votre système est prévenu au moment où cela arrive : un passeport créé, un propriétaire déclaré, une garantie activée, un entretien inscrit, une montre déplacée dans un stock. Chaque appel est signé, et renvoyé en cas d'échec.
Ce dont votre système est prévenu
Watch Certificate™ appelle votre système quand il arrive quelque chose à une montre ou à un passeport que votre compte lit par l'API, et à aucun autre. Chaque événement est un POST HTTPS vers votre adresse, signé avec un secret que seuls vous et Watch Certificate™ détenez.
| Événement | type | Quand il est envoyé |
|---|---|---|
| Montre créée | passport.created | Une montre est créée, puis à nouveau quand sa carte est liée et qu'elle devient un passeport. |
| Propriétaire déclaré | owner.declared | Un propriétaire est déclaré sur un passeport, à une vente ou à un transfert. L'événement nomme qui l'a déclaré, jamais le propriétaire. |
| Garantie activée | warranty.activated | La garantie d'un passeport est activée, avec ses dates de début et de fin ; elle peut commencer un jour plus tard. |
| Entretien inscrit | service_event.created | Un professionnel ajoute un événement à l'historique d'un passeport : un entretien, une réparation. Les événements personnels d'un propriétaire ne sont jamais envoyés. |
| Stock déplacé | stock.moved | Une montre est confiée à un détaillant, reprise par sa manufacture, transférée à un autre de ses détaillants, ou vendue. Le détaillant qu'elle quitte est prévenu aussi ; un acheteur n'est jamais nommé. |
Chaque événement a le même corps : son id, son type, le moment où il est arrivé (createdAt) et ses data. Des identifiants seulement, jamais le nom, l'email, le téléphone ni l'adresse d'une personne : lisez le reste par l'API avec ces identifiants.
{
"id": "00000000-0000-4000-8000-000000000000",
"type": "passport.created",
"createdAt": "2026-01-15T10:00:00.000Z",
"data": {
"certificateId": "00000000-0000-4000-8000-000000000000",
"watchId": "00000000-0000-4000-8000-000000000000",
"certificateCardId": "ABC123456",
"externalRef": "my-ref-42"
}
}Le régler dans l'app
Avec un compte professionnel ou assureur, dans Paramètres, Configuration, Webhooks :
- Ajouter un webhook : l'adresse de votre système, en
httpset sur l'internet public, et les événements qu'il reçoit. - Secret de signature : affiché une seule fois, quand le webhook est ajouté ou son secret renouvelé. Copiez-le à ce moment et gardez-le sur votre serveur ; s'il est perdu, utilisez « Renouveler le secret ».
- Envoyer un test : un événement
ping, envoyé tout de suite, pour essayer votre adresse et votre vérification de la signature. - Derniers envois : chaque envoi, son statut, ses tentatives et la dernière réponse de votre système.
Vérifier la signature
Chaque appel porte ces en-têtes :
X-WC-Event: letypede l'événement ;X-WC-Delivery: l'identifiant de l'événement (id), le même à chaque nouvelle tentative ;X-WC-Timestamp: le moment où cette tentative a été signée, en secondes Unix ;X-WC-Signature:v1=puis le HMAC-SHA256 en hexadécimal, avec votre secret entier pour clé, de<X-WC-Timestamp>.<raw body>.
Vérifiez-la avant de vous fier à un corps : calculez le HMAC sur le corps brut tel que reçu, jamais sur un JSON que vous avez lu puis réécrit, comparez-le en temps constant, et refusez un horodatage à plus de cinq minutes de votre horloge.
En Node.js (avec Express, lisez le corps brut sur cette route : express.raw({ type: 'application/json' })) :
const crypto = require('crypto');
// nowSeconds: your clock, in Unix seconds
function verify(rawBody, headers, secret, nowSeconds) {
const timestamp = Number(headers['x-wc-timestamp']);
const signature = String(headers['x-wc-signature'] || '');
if (!Number.isFinite(timestamp) || Math.abs(nowSeconds - timestamp) > 300) {
return false;
}
const expected =
'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`, 'utf8').digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Réponses, nouvelles tentatives et pauses
- Répondez tout de suite : un 2xx en moins de 10 secondes, puis faites votre travail. Toute autre réponse, une redirection ou un délai dépassé est un échec.
- Nouvelles tentatives : après un échec, Watch Certificate™ essaie à nouveau 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures et 12 heures plus tard, puis abandonne l'envoi.
- Pause : après 20 tentatives échouées d'affilée sur 3 heures au moins, le webhook est mis en pause. Corrigez votre système, envoyez un test, puis reprenez-le.
- Rythme : 10 envois par webhook et par minute au plus, les autres attendent leur tour.
- En double, ou dans le désordre : un envoi peut vous arriver deux fois, et les événements dans le désordre. Ignorez un
X-WC-Deliverydéjà traité, et lisez l'API pour l'état actuel. - Pas d'adresse fixe : les envois partent des serveurs cloud de Watch Certificate™, sans adresse IP fixe. Ne filtrez pas par adresse : vérifiez la signature.
La référence
La référence de l'API décrit les webhooks en entier : un exemple des données de chaque événement, chaque en-tête, et la vérification de la signature en Python aussi.
Elle est ouverte, sans identifiants, à l'adresse https://.