記事 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)から:

  1. Webhookを追加:お客様のシステムのアドレス(https、公開インターネット上)と、受け取るイベント。
  2. 署名シークレット:Webhookの追加時またはシークレットの更新時に一度だけ表示されます。その場でコピーしてサーバーに保管してください。紛失した場合は「シークレットを更新」を使います。
  3. テストを送信:ping イベントをすぐに送信し、アドレスと署名の検証を試せます。
  4. 最近の送信:各送信のステータス、試行回数、システムからの最後の応答。

署名の検証

各呼び出しには次のヘッダーが付きます:

  • 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://api.watchcertificate.org/api/v1/doc で公開されています。