用途:该技能面向需要接收与验证 Treezor Webhook 的开发者,适用于搭建 Treezor 回调处理程序、调试签名验证,以及处理 BaaS 银行事件(如 payin.create、cardtransaction.create、user.kycreview)。
主要能力:Treezor 使用自定义 HMAC-SHA256 方案,签名不是 HTTP 头,而是 JSON 正文中的 object_payload_signature 字段;Webhook 以 text/plain 到达,需自行解析正文。验证时需把 object_payload 重新序列化为 Treezor 规范形式(紧凑分隔符、斜杠转义为 /、非 ASCII 转义为小写 \uXXXX),再用 webhook_secret 做 HMAC-SHA256、base64 编码并做时序安全比较。资料提供了 Node 与 Python 的 canonicalize/verify 示例。
使用方式:设置环境变量 TREEZOR_WEBHOOK_SECRET。Webhook 管理主机与主 API 不同:生产为 https://webhook.api.treezor.co,沙箱为 https://webhook.sandbox.treezor.co;通过 POST /settings/hooks 订阅,再用 /settings/hooks/{uuid}/events 管理事件,新订阅初始为 PENDING。本地开发可用 npx hookdeck-cli listen 3000 treezor --path /webhooks/treezor。
限制与注意:只有 object_payload 被签名,信封字段(webhook、webhook_id、object、object_id)不在签名范围内,验证成功后仍不可信,仅用于日志与路由,业务状态应从已验证的 object_payload 推导,涉及资金或 KYC 决策应重新调用 Treezor API。成功返回 200,返回 5xx 触发重试(每分钟一次,最多 30 次);投递按时间顺序但不保证顺序且可能重复,应按 webhook_id 去重。签名基于重新序列化的 object_payload 而非原始请求体,若规范字符串不能逐字节匹配(斜杠转义、\uXXXX 大小写、键顺序)则验证失败。事件名遵循 object.action 模式,部分对象为 camelCase 或多段(如 sca.wallet.create、qes.created)。完整事件参考见 Treezor Webhooks 文档。