Artículo 9 de 9
Recibir los eventos de sus relojes (webhooks)
Su sistema recibe el aviso en el momento en que ocurre: un pasaporte creado, un propietario declarado, una garantía activada, un mantenimiento registrado, un reloj movido en un stock. Cada llamada va firmada y se reenvía si falla.
De qué se avisa a su sistema
Watch Certificate™ llama a su sistema cuando le ocurre algo a un reloj o a un pasaporte que su cuenta lee a través de la API, y a ningún otro. Cada evento es un POST HTTPS a su dirección, firmado con un secreto que solo usted y Watch Certificate™ conocen.
| Evento | type | Cuándo se envía |
|---|---|---|
| Reloj creado | passport.created | Se crea un reloj, y de nuevo cuando se vincula su tarjeta y se convierte en pasaporte. |
| Propietario declarado | owner.declared | Se declara un propietario en un pasaporte, en una venta o una transferencia. El evento indica quién lo declaró, nunca el propietario. |
| Garantía activada | warranty.activated | Se activa la garantía de un pasaporte, con sus fechas de inicio y de fin; puede empezar un día posterior. |
| Mantenimiento registrado | service_event.created | Un profesional añade un evento al historial de un pasaporte: un mantenimiento, una reparación. Los eventos personales de un propietario nunca se envían. |
| Stock movido | stock.moved | Un reloj se confía a un minorista, su fabricante lo recupera, se transfiere a otro de sus minoristas o se vende. El minorista del que sale también recibe el aviso; nunca se nombra a un comprador. |
Cada evento tiene el mismo cuerpo: su id, su type, cuándo ocurrió (createdAt) y sus data. Solo identificadores, nunca el nombre, el correo electrónico, el teléfono ni la dirección de una persona: lea el resto a través de la API con esos identificadores.
{
"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 en la aplicación
Con una cuenta profesional o de aseguradora, en Ajustes, Configuración, Webhooks:
- Añadir un webhook: la dirección de su sistema, en
httpsy en internet pública, y los eventos que recibe. - Secreto de firma: se muestra una sola vez, cuando se añade el webhook o se renueva su secreto. Cópielo entonces y guárdelo en su servidor; si lo pierde, use «Renovar el secreto».
- Enviar una prueba: un evento
ping, enviado al momento, para probar su dirección y su comprobación de la firma. - Últimos envíos: cada envío, su estado, sus intentos y la última respuesta de su sistema.
Comprobar la firma
Cada llamada lleva estos encabezados:
X-WC-Event: eltypedel evento;X-WC-Delivery: eliddel evento, el mismo en cada reintento;X-WC-Timestamp: cuándo se firmó este intento, en segundos Unix;X-WC-Signature:v1=y luego el HMAC-SHA256 en hexadecimal, con su secreto completo como clave, de<X-WC-Timestamp>.<raw body>.
Compruébela antes de confiar en un cuerpo: calcule el HMAC sobre el cuerpo en bruto tal como se recibe, nunca sobre un JSON que haya leído y vuelto a escribir, compárelo en tiempo constante y rechace una marca de tiempo a más de cinco minutos de su reloj.
En Node.js (con Express, lea el cuerpo en bruto en esta ruta: 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);
}Respuestas, reintentos y pausas
- Responda enseguida: un 2xx en menos de 10 segundos, y luego haga su trabajo. Cualquier otra respuesta, una redirección o un tiempo agotado es un fallo.
- Reintentos: tras un fallo, Watch Certificate™ lo intenta de nuevo 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 12 horas después, y luego abandona el envío.
- Pausa: tras 20 intentos fallidos seguidos durante al menos 3 horas, el webhook se pausa. Corrija su sistema, envíe una prueba y luego reanúdelo.
- Ritmo: 10 envíos por webhook y por minuto como máximo, los demás esperan su turno.
- Duplicados o desordenados: un envío puede llegarle dos veces, y los eventos pueden llegar desordenados. Omita un
X-WC-Deliveryya procesado y lea la API para conocer el estado actual. - Sin dirección fija: los envíos salen de los servidores en la nube de Watch Certificate™, sin dirección IP fija. No filtre por dirección: compruebe la firma.
La referencia
La referencia de la API describe los webhooks por completo: un ejemplo de los datos de cada evento, cada encabezado y la comprobación de la firma también en Python.
Está abierta, sin credenciales, en https://.