用途:帮助开发者搭建 Bridge(bridge.xyz)Webhook 接收端,并正确验证 X-Webhook-Signature 签名,适用于处理 customer、kyc_link、transfer、virtual_account 等事件,以及排查签名验证失败问题。
主要能力:Bridge 是稳定币编排平台,涵盖客户、KYC 链接、转账、虚拟账户、卡等业务。其 Webhook 使用 RSA-SHA256 签名,通过创建/更新 Webhook 时返回的每端点 PEM 公钥验证,没有 HMAC 共享密钥,也没有官方 SDK。签名头格式为 X-Webhook-Signature: t=<timestamp_ms>,v0=<base64_signature>。验证时须使用原始请求体,不能先 JSON.parse。特殊之处:Bridge 先对 <timestamp>.<rawBody> 做 SHA256 得到摘要,再用 RSA-SHA256 验证该摘要,因此摘要会在验证器内部被再次哈希,需把摘要(而非原始字符串)传入 RSA-SHA256 验证器。验证失败应返回非 2xx(文档示例为 400),以便 Bridge 重试。
使用方式:订阅按类别(event_categories 数组)而非单个事件进行。常见事件包括 customer.created、customer.updated、kyc_link.updated、transfer.created、transfer.updated、virtual_account.activity。环境变量 BRIDGE_WEBHOOK_PUBLIC_KEY 存放单行 PEM 公钥(含字面 \n,示例会转换回换行)。本地开发可用 npx hookdeck-cli listen 3000 bridge-xyz --path /webhooks/bridge-xyz 启动隧道。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。
适用场景与限制:适合需要接收 Bridge 事件并做幂等处理的支付/稳定币集成。资料未提供官方 SDK、HMAC 密钥或具体收费信息;建议配合 webhook-handler-patterns 技能处理处理顺序、幂等、错误处理与重试逻辑。