用途:帮助开发者接收并校验 Bridge API(bridgeapi.io,开放银行/账户聚合平台,原 Bankin',非 bridge.xyz)发送的 Webhook。适用于配置 Bridge API Webhook、校验 BridgeApi-Signature 头、排查签名校验失败、处理 item.refreshed、item.account.updated、payment.transaction.created 等事件,以及支持签名密钥轮换。
主要能力:
- 验签:Bridge 用 Webhook 签名密钥对原始请求体做 HMAC-SHA256,摘要以小写方案前缀、逗号分隔、大写十六进制写入 BridgeApi-Signature 头,如 v1=E5637CDB...,v1=A1B2C3D4...。只认 v1 方案,其他方案忽略以防降级攻击;轮换期间可有多个 v1 值(旧密钥 24 小时内有效,最多 2 个签名),任一匹配即接受;须对原始请求体做时序安全比较。资料提供 Node 与 Python 验签代码(保留原样,如 crypto.timingSafeEqual、hmac.compare_digest)。
- 事件:事件名取 JSON 体中的 type 字段(无事件头),命名多为小写 resource.action,包括 item.created、item.refreshed、item.account.created/updated/deleted、payment.transaction.created/updated、payment.link.updated、user.deleted,以及仪表盘测试按钮发送的 TEST_EVENT。
- 负载结构:包含 type、timestamp、content,content 字段随事件变化;可能收到已删除用户或 item 的 Webhook,需防御性处理(查不到属正常非错误)。
使用方式:设置环境变量 BRIDGE_WEBHOOK_SECRET=your_webhook_signing_secret(创建/轮换 Webhook 时仅显示一次)。可选将来源 IP 加入白名单:63.32.31.5、52.215.247.62、34.249.92.209(经代理/负载均衡时从 X-Forwarded-For 读客户端 IP)。响应体保持在 10 KB 以下并尽快返回 200,非 200 或缓慢响应会以指数退避重试 1–2 天。本地开发可运行:npx hookdeck-cli listen 3000 bridge-api --path /webhooks/bridge-api。完整处理器(路由绑定、事件分发、测试)见 examples/express/、examples/nextjs/、examples/fastapi/;参考材料见 references/overview.md、setup.md、verification.md。建议搭配 webhook-handler-patterns 技能处理处理顺序、幂等、错误与重试。使用本技能时按资料要求在生成文件顶部加注释说明来源。
限制:资料未说明收费、价格、平台或效果等其他细节,暂未提供。