Articolo 9 di 9

Ricevere gli eventi dei tuoi orologi (webhook)

Il tuo sistema viene avvisato nel momento in cui accade: un passaporto creato, un proprietario dichiarato, una garanzia attivata, una manutenzione registrata, un orologio spostato in uno stock. Ogni chiamata è firmata e reinviata in caso di errore.

Di cosa viene avvisato il tuo sistema

Watch Certificate™ chiama il tuo sistema quando succede qualcosa a un orologio o a un passaporto che il tuo account legge tramite l'API, e a nessun altro. Ogni evento è un POST HTTPS al tuo indirizzo, firmato con un segreto che solo tu e Watch Certificate™ conoscete.

EventotypeQuando viene inviato
Orologio creatopassport.createdViene creato un orologio, poi di nuovo quando la sua carta viene collegata e diventa un passaporto.
Proprietario dichiaratoowner.declaredViene dichiarato un proprietario su un passaporto, a una vendita o a un trasferimento. L'evento indica chi lo ha dichiarato, mai il proprietario.
Garanzia attivatawarranty.activatedViene attivata la garanzia di un passaporto, con le sue date di inizio e di fine; può iniziare in un giorno successivo.
Manutenzione registrataservice_event.createdUn professionista aggiunge un evento alla cronologia di un passaporto: una manutenzione, una riparazione. Gli eventi personali di un proprietario non vengono mai inviati.
Stock spostatostock.movedUn orologio viene affidato a un rivenditore, ritirato dalla sua manifattura, trasferito a un altro dei suoi rivenditori o venduto. Anche il rivenditore che lascia viene avvisato; un acquirente non viene mai nominato.

Ogni evento ha lo stesso corpo: il suo id, il suo type, quando è accaduto (createdAt) e i suoi data. Solo identificativi, mai il nome, l'email, il telefono o l'indirizzo di una persona: leggi il resto tramite l'API con questi identificativi.

{
  "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"
  }
}

Configurarlo nell'app

Con un account professionale o di assicuratore, in Impostazioni, Configurazione, Webhook:

  1. Aggiungi un webhook: l'indirizzo del tuo sistema, in https e su internet pubblico, e gli eventi che riceve.
  2. Segreto di firma: mostrato una sola volta, quando il webhook viene aggiunto o il suo segreto rinnovato. Copialo in quel momento e conservalo sul tuo server; se lo perdi, usa «Rinnova il segreto».
  3. Invia un test: un evento ping, inviato subito, per provare il tuo indirizzo e la tua verifica della firma.
  4. Ultimi invii: ogni invio, il suo stato, i suoi tentativi e l'ultima risposta del tuo sistema.

Verificare la firma

Ogni chiamata contiene queste intestazioni:

  • X-WC-Event: il type dell'evento;
  • X-WC-Delivery: l'identificativo dell'evento (id), lo stesso a ogni nuovo tentativo;
  • X-WC-Timestamp: quando è stato firmato questo tentativo, in secondi Unix;
  • X-WC-Signature: v1= poi l'HMAC-SHA256 in esadecimale, con il tuo segreto intero come chiave, di <X-WC-Timestamp>.<raw body>.

Verificala prima di fidarti di un corpo: calcola l'HMAC sul corpo grezzo così come ricevuto, mai su un JSON che hai letto e riscritto, confrontalo in tempo costante e rifiuta un timestamp che si discosta di più di cinque minuti dal tuo orologio.

In Node.js (con Express, leggi il corpo grezzo su questa 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);
}

Risposte, nuovi tentativi e pause

  • Rispondi subito: un 2xx entro 10 secondi, poi fai il tuo lavoro. Qualsiasi altra risposta, un reindirizzamento o un timeout è un errore.
  • Nuovi tentativi: dopo un errore, Watch Certificate™ riprova 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e 12 ore dopo, poi rinuncia all'invio.
  • Pausa: dopo 20 tentativi falliti di fila su almeno 3 ore, il webhook viene messo in pausa. Correggi il tuo sistema, invia un test, poi riprendilo.
  • Ritmo: al massimo 10 invii per webhook al minuto, gli altri attendono il proprio turno.
  • Doppi o fuori ordine: un invio può arrivarti due volte, e gli eventi possono arrivare fuori ordine. Salta un X-WC-Delivery già gestito, e leggi l'API per lo stato attuale.
  • Nessun indirizzo fisso: gli invii partono dai server cloud di Watch Certificate™, senza indirizzo IP fisso. Non filtrare per indirizzo: verifica la firma.

Il riferimento

Il riferimento dell'API descrive i webhook per intero: un esempio dei dati di ogni evento, ogni intestazione e la verifica della firma anche in Python.

È aperto, senza credenziali, all'indirizzo https://api.watchcertificate.org/api/v1/doc.