Article 9 of 9
Receive your watches' events (webhooks)
Your system is told as it happens: a passport created, an owner declared, a warranty activated, a service recorded, a watch moved in a stock. Each call is signed, and sent again if it fails.
What your system is told
Watch Certificate™ calls your system when something happens to a watch or a passport your account reads through the API, and to no other. Each event is an HTTPS POST to your address, signed with a secret only you and Watch Certificate™ hold.
| Event | type | When it is sent |
|---|---|---|
| Watch created | passport.created | A watch is created, then again when its card is linked and it becomes a passport. |
| Owner declared | owner.declared | An owner is declared on a passport, at a sale or a transfer. The event names who declared it, never the owner. |
| Warranty activated | warranty.activated | A passport's warranty is activated, with its start and end dates; it may start on a later day. |
| Service recorded | service_event.created | A professional adds an event to a passport's history: a service, a repair. An owner's personal events are never sent. |
| Stock moved | stock.moved | A watch is placed with a retailer, taken back by its manufacture, transferred to another of its retailers, or sold. The retailer it leaves is told too; a buyer is never named. |
Every event has the same body: its id, its type, when it happened (createdAt) and its data. Ids only, never a person's name, email, phone or address: read the rest through the API with those ids.
{
"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"
}
}Setting it up in the app
With a professional or an insurer account, in Settings, Configuration, Webhooks:
- Add a webhook: your system's address, in
httpsand on the public internet, and the events it receives. - Signing secret: shown once, when the webhook is added or its secret renewed. Copy it then and keep it on your server; if it is lost, use “Renew the secret”.
- Send a test: a
pingevent, sent at once, to try your address and your signature check. - Recent deliveries: each delivery, its status, its attempts and your system's last answer.
Checking the signature
Each call carries these headers:
X-WC-Event: the event'stype;X-WC-Delivery: the event'sid, the same at every retry;X-WC-Timestamp: when this attempt was signed, in Unix seconds;X-WC-Signature:v1=then the HMAC-SHA256 in hex, keyed by your whole secret, of<X-WC-Timestamp>.<raw body>.
Check it before trusting a body: compute the HMAC over the raw body as received, never over a JSON you parsed and wrote again, compare it in constant time, and refuse a timestamp more than five minutes away from your clock.
In Node.js (with Express, read the body raw on this 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);
}Answers, retries and pauses
- Answer at once: a 2xx within 10 seconds, then do your work. Any other answer, a redirect or a timeout is a failure.
- Retries: after a failure, Watch Certificate™ tries again 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours later, then gives the delivery up.
- Pause: after 20 failed attempts in a row over 3 hours at least, the webhook is paused. Fix your system, send a test, then resume it.
- Pace: 10 deliveries per webhook each minute at most, the others wait their turn.
- Twice, or out of order: a delivery may reach you twice, and events may arrive out of order. Skip an
X-WC-Deliveryyou already handled, and read the API for the current state. - No fixed address: deliveries come from Watch Certificate™'s cloud servers, with no fixed IP address. Do not filter by address: check the signature.
The reference
The API's reference describes the webhooks in full: an example of each event's data, every header, and the signature check in Python too.
It is open, with no credentials, at https://.