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énementtypeQuand il est envoyé
Montre crééepassport.createdUne montre est créée, puis à nouveau quand sa carte est liée et qu'elle devient un passeport.
Propriétaire déclaréowner.declaredUn 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éewarranty.activatedLa garantie d'un passeport est activée, avec ses dates de début et de fin ; elle peut commencer un jour plus tard.
Entretien inscritservice_event.createdUn 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.movedUne 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 :

  1. Ajouter un webhook : l'adresse de votre système, en https et sur l'internet public, et les événements qu'il reçoit.
  2. 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 ».
  3. Envoyer un test : un événement ping, envoyé tout de suite, pour essayer votre adresse et votre vérification de la signature.
  4. 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 : le type de 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-Delivery dé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://api.watchcertificate.org/api/v1/doc.