Artikel 9 von 9
Die Ereignisse Ihrer Uhren empfangen (Webhooks)
Ihr System wird in dem Moment informiert, in dem es geschieht: ein Uhrenpass erstellt, ein Eigentümer erfasst, eine Garantie aktiviert, ein Service eingetragen, eine Uhr in einem Bestand verschoben. Jeder Aufruf ist signiert und wird bei einem Fehler erneut gesendet.
Worüber Ihr System informiert wird
Watch Certificate™ ruft Ihr System auf, sobald etwas mit einer Uhr oder einem Uhrenpass geschieht, auf die Ihr Konto über die API Zugriff hat, und für keine anderen. Jedes Ereignis ist ein HTTPS-POST an Ihre Adresse, signiert mit einem Geheimnis, das nur Sie und Watch Certificate™ kennen.
| Ereignis | type | Wann es gesendet wird |
|---|---|---|
| Uhr erstellt | passport.created | Eine Uhr wird erstellt, dann erneut, wenn ihre Karte verknüpft wird und sie zum Uhrenpass wird. |
| Eigentümer erfasst | owner.declared | Ein Eigentümer wird für einen Uhrenpass erfasst, bei einem Verkauf oder einer Übertragung. Das Ereignis nennt, wer ihn erfasst hat, niemals den Eigentümer. |
| Garantie aktiviert | warranty.activated | Die Garantie eines Uhrenpasses wird aktiviert, mit Beginn- und Enddatum; sie kann an einem späteren Tag beginnen. |
| Service eingetragen | service_event.created | Ein Profi fügt der Historie eines Uhrenpasses ein Ereignis hinzu: einen Service, eine Reparatur. Die persönlichen Ereignisse eines Eigentümers werden nie gesendet. |
| Bestand verschoben | stock.moved | Eine Uhr wird einem Fachhändler übergeben, von ihrem Hersteller zurückgenommen, an einen anderen seiner Fachhändler übertragen oder verkauft. Der Fachhändler, den sie verlässt, wird ebenfalls informiert; ein Käufer wird nie genannt. |
Jedes Ereignis hat denselben Body: seine id, seinen type, wann es geschah (createdAt), und seine data. Nur IDs, nie Name, E-Mail, Telefon oder Adresse einer Person: Den Rest lesen Sie mit diesen IDs über die API.
{
"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"
}
}In der App einrichten
Mit einem professionellen Konto oder einem Versichererkonto, unter Einstellungen, Konfiguration, Webhooks:
- Webhook hinzufügen: die Adresse Ihres Systems, mit
httpsund im öffentlichen Internet, und die Ereignisse, die es erhält. - Signaturgeheimnis: nur einmal angezeigt, wenn der Webhook hinzugefügt oder sein Geheimnis erneuert wird. Kopieren Sie es dann und bewahren Sie es auf Ihrem Server auf; geht es verloren, nutzen Sie „Geheimnis erneuern“.
- Test senden: ein
ping-Ereignis, sofort gesendet, um Ihre Adresse und Ihre Signaturprüfung zu testen. - Letzte Zustellungen: jede Zustellung, ihr Status, ihre Versuche und die letzte Antwort Ihres Systems.
Die Signatur prüfen
Jeder Aufruf enthält diese Header:
X-WC-Event: dertypedes Ereignisses;X-WC-Delivery: dieiddes Ereignisses, bei jedem erneuten Versuch dieselbe;X-WC-Timestamp: wann dieser Versuch signiert wurde, in Unix-Sekunden;X-WC-Signature:v1=, dann der HMAC-SHA256 in Hex, mit Ihrem vollständigen Geheimnis als Schlüssel, über<X-WC-Timestamp>.<raw body>.
Prüfen Sie sie, bevor Sie einem Body vertrauen: Berechnen Sie den HMAC über den Roh-Body, wie er ankommt, nie über ein JSON, das Sie geparst und neu geschrieben haben, vergleichen Sie in konstanter Zeit und lehnen Sie einen Zeitstempel ab, der mehr als fünf Minuten von Ihrer Uhrzeit abweicht.
In Node.js (mit Express lesen Sie den Body auf dieser Route roh: 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);
}Antworten, Wiederholungen und Pausen
- Sofort antworten: ein 2xx innerhalb von 10 Sekunden, dann erledigen Sie Ihre Arbeit. Jede andere Antwort, eine Weiterleitung oder eine Zeitüberschreitung ist ein Fehlschlag.
- Wiederholungen: Nach einem Fehlschlag versucht es Watch Certificate™ 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 12 Stunden später erneut und gibt die Zustellung dann auf.
- Pause: Nach 20 fehlgeschlagenen Versuchen in Folge über mindestens 3 Stunden wird der Webhook pausiert. Beheben Sie den Fehler in Ihrem System, senden Sie einen Test und setzen Sie ihn dann fort.
- Takt: höchstens 10 Zustellungen pro Webhook und Minute, die anderen warten, bis sie an der Reihe sind.
- Doppelt oder in anderer Reihenfolge: Eine Zustellung kann Sie zweimal erreichen, und Ereignisse können in anderer Reihenfolge eintreffen. Überspringen Sie eine bereits verarbeitete
X-WC-Deliveryund lesen Sie den aktuellen Stand über die API. - Keine feste Adresse: Die Zustellungen kommen von den Cloud-Servern von Watch Certificate™, ohne feste IP-Adresse. Filtern Sie nicht nach Adresse: Prüfen Sie die Signatur.
Die Referenz
Die Referenz der API beschreibt die Webhooks vollständig: ein Beispiel der Daten jedes Ereignisses, jeden Header und die Signaturprüfung auch in Python.
Sie ist ohne Zugangsdaten unter https:// frei zugänglich.