第 9 篇,共 9 篇

接收您手表的事件(Webhook)

事件发生时即时通知您的系统:护照创建、所有者登记、保修激活、保养记录、手表在库存中变动。每次调用都带有签名,失败时会重新发送。

您的系统会收到哪些通知

当您的账户可通过 API 读取的手表或护照发生变化时,Watch Certificate™ 会调用您的系统,其他手表或护照则不会。每个事件都是发往您地址的 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(十六进制)。

在信任请求体之前先校验签名:对收到的原始请求体计算 HMAC,绝不对解析后重新生成的 JSON 计算;以恒定时间比较;拒绝与您的时钟相差超过五分钟的时间戳。

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 每分钟最多发送 10 次,其余的排队等候。
  • 重复或乱序:同一次发送可能到达两次,事件也可能乱序到达。请跳过已处理过的 X-WC-Delivery,并通过 API 读取当前状态。
  • 无固定地址:发送来自 Watch Certificate™ 的云服务器,没有固定 IP 地址。请勿按地址过滤:请校验签名。

参考文档

API 参考文档完整介绍了 Webhook:每个事件数据的示例、每个请求头,以及 Python 版的签名校验。

它无需登录凭据即可访问,地址为 https://api.watchcertificate.org/api/v1/doc。