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.
| Evento | type | Quando viene inviato |
|---|---|---|
| Orologio creato | passport.created | Viene creato un orologio, poi di nuovo quando la sua carta viene collegata e diventa un passaporto. |
| Proprietario dichiarato | owner.declared | Viene dichiarato un proprietario su un passaporto, a una vendita o a un trasferimento. L'evento indica chi lo ha dichiarato, mai il proprietario. |
| Garanzia attivata | warranty.activated | Viene attivata la garanzia di un passaporto, con le sue date di inizio e di fine; può iniziare in un giorno successivo. |
| Manutenzione registrata | service_event.created | Un professionista aggiunge un evento alla cronologia di un passaporto: una manutenzione, una riparazione. Gli eventi personali di un proprietario non vengono mai inviati. |
| Stock spostato | stock.moved | Un 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:
- Aggiungi un webhook: l'indirizzo del tuo sistema, in
httpse su internet pubblico, e gli eventi che riceve. - 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».
- Invia un test: un evento
ping, inviato subito, per provare il tuo indirizzo e la tua verifica della firma. - 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: iltypedell'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-Deliverygià 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://.