記事 9 / 9
時計のイベントを受け取る(Webhook)
パスポートの作成、所有者の登録、保証の有効化、メンテナンスの記録、在庫内の時計の移動を、その時点でお客様のシステムに通知します。各呼び出しには署名が付き、失敗した場合は再送されます。
システムに通知される内容
Watch Certificate™は、お客様のアカウントがAPIで読み取れる時計やパスポートに何かが起きたときに、お客様のシステムを呼び出します。それ以外の時計やパスポートについては呼び出しません。各イベントはお客様のアドレスへのHTTPS POSTで、お客様とWatch Certificate™だけが持つシークレットで署名されます。
| イベント | type | 送信されるタイミング |
|---|---|---|
| 時計の作成 | passport.created | 時計が作成されたとき。さらに、カードが紐付けられてパスポートになったときにも送信されます。 |
| 所有者の登録 | owner.declared | 販売や譲渡で、パスポートに所有者が登録されたとき。イベントには登録した人が示され、所有者は含まれません。 |
| 保証の有効化 | warranty.activated | パスポートの保証が有効化されたとき。開始日と終了日が含まれます。保証の開始日が後日になる場合もあります。 |
| メンテナンスの記録 | service_event.created | プロがパスポートの履歴にメンテナンスや修理などのイベントを追加したとき。所有者の個人的なイベントは送信されません。 |
| 在庫の移動 | stock.moved | 時計が小売業者に預けられたとき、メーカーに引き取られたとき、同じメーカーの別の小売業者へ移管されたとき、または販売されたとき。時計が離れる小売業者にも通知されます。購入者の名前が示されることはありません。 |
どのイベントも本文の形は同じです:id、type、発生日時(createdAt)、data。含まれるのはIDだけで、個人の氏名、メールアドレス、電話番号、住所は含まれません。その他の情報は、これらのIDを使って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"
}
}アプリでの設定
プロフェッショナルアカウントまたは保険会社のアカウントで、アプリの設定(Webhook)から:
- Webhookを追加:お客様のシステムのアドレス(
https、公開インターネット上)と、受け取るイベント。 - 署名シークレット:Webhookの追加時またはシークレットの更新時に一度だけ表示されます。その場でコピーしてサーバーに保管してください。紛失した場合は「シークレットを更新」を使います。
- テストを送信:
pingイベントをすぐに送信し、アドレスと署名の検証を試せます。 - 最近の送信:各送信のステータス、試行回数、システムからの最後の応答。
署名の検証
各呼び出しには次のヘッダーが付きます:
X-WC-Event:イベントのtype。X-WC-Delivery:イベントのid。再試行でも同じです。X-WC-Timestamp:この試行が署名された日時(Unix秒)。X-WC-Signature:v1=に続けて、シークレット全体をキーとした<X-WC-Timestamp>.<raw body>のHMAC-SHA256(16進数)。
本文を信頼する前に必ず検証してください。HMACは受信したままの生の本文で計算し、解析して書き直したJSONでは計算しないこと。比較は定数時間で行い、お客様の時計と5分以上ずれたタイムスタンプは拒否してください。
Node.jsの例(Expressでは、このルートで本文を生のまま読み取ります: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);
}応答、再試行、一時停止
- すぐに応答:10秒以内に2xxを返し、その後で処理を行ってください。それ以外の応答、リダイレクト、タイムアウトは失敗になります。
- 再試行:失敗すると、Watch Certificate™は1分後、5分後、30分後、2時間後、6時間後、12時間後に再試行し、その後は送信を断念します。
- 一時停止:少なくとも3時間にわたって20回連続で失敗すると、Webhookは一時停止されます。システムを修正し、テストを送信してから再開してください。
- 送信ペース:Webhookごとに1分あたり最大10件。それ以外は順番を待ちます。
- 重複や順序の入れ替わり:同じ送信が2回届くことや、イベントの順序が入れ替わることがあります。処理済みの
X-WC-Deliveryはスキップし、現在の状態はAPIで読み取ってください。 - 固定アドレスなし:送信はWatch Certificate™のクラウドサーバーから行われ、固定IPアドレスはありません。アドレスでフィルタリングせず、署名を検証してください。
リファレンス
APIのリファレンスでは、Webhookのすべてを説明しています。各イベントのデータの例、すべてのヘッダー、Pythonでの署名の検証も掲載しています。
認証情報なしで、https:// で公開されています。