第 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”中:
- 添加 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(十六进制)。
在信任请求体之前先校验签名:对收到的原始请求体计算 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://。