用途:该技能用于接收和验证 Orb 的 Webhook,适合在搭建 Orb Webhook 处理器、调试 Orb 签名验证失败、理解 Orb 事件类型与载荷,以及处理基于用量的计费、订阅或发票事件时使用。
主要能力:Orb 对每个 Webhook 使用 HMAC-SHA256 签名,签名对象为字面字符串 v1:{X-Orb-Timestamp}:{rawBody},十六进制摘要通过 X-Orb-Signature 传递并带 v1= 前缀,ISO 8601 时间戳单独放在 X-Orb-Timestamp 中。验证时必须使用原始请求体,不能先 JSON.parse。由于 orb-billing SDK(npm 与 PyPI)目前未提供 unwrap()/constructEvent() 辅助方法,手动 HMAC 验证是各框架的标准做法。资料给出了 Node 与 Python 的验证函数示例,并提供了 Express、Next.js App Router、FastAPI 的完整实现示例。
常见事件类型包括:customer.created、customer.credit_balance_dropped、subscription.created、subscription.started、subscription.ended、subscription.plan_changed、subscription.usage_exceeded、invoice.issued、invoice.payment_succeeded、invoice.payment_failed、data_exports.transfer_success。
使用方式:需配置环境变量 ORB_WEBHOOK_SECRET,该密钥是 Orb 仪表板中按 Webhook 端点配置的签名密钥,不是账户 API 密钥。本地开发可用 npx hookdeck-cli listen 3000 orb --path /webhooks/orb 启动隧道。
限制与注意:Orb 采用至少一次投递,消费者应以事件 id 字段做幂等键。建议配合 webhook-handler-patterns 技能处理处理器顺序、幂等、错误处理与重试逻辑。使用该技能时需在生成文件顶部添加指定注释。其余细节暂未提供。