用途:帮助开发者在应用中接收并验证 Ascend 发送的 Webhook。Ascend(保险支付/保费融资)在事件发生时向你的 HTTPS 端点 POST JSON 负载,并用 HMAC-SHA256 签名,必须先验证再信任事件。
主要能力:采用 Stripe 风格的自定义 HMAC-SHA256 方案(非 Svix、非 Standard Webhooks),发送 X-Ascend-Signature(形如 t=1696200697,v1=5257a869e7...)和 X-Ascend-Request-Timestamp 两个头。验证流程:解析签名为 t 与 v1;以 ${t}:${rawBody} 构建待签字符串;用 webhook_secret 计算 HMAC-SHA256 并十六进制编码;与 v1 做常量时间比较。必须使用原始请求体,重新序列化 JSON 会改变字节导致验签失败。无官方 Ascend SDK,各框架均需手动验证。
事件与负载:顶层结构统一,data 直接是资源对象(无 data.object 包装),例如 id、type、data{ id, status, payee, payer_name, total_amount_cents, invoice_number, paid_at }。常见类型含 invoice.created、invoice.processing_payment、invoice.paid、invoice.voided、invoice.marked_overdue、payout.paying、payout.paid、payout.on_hold、payout.canceled、payout.failed、refund.paid、refund.cancelled;应基于 type 分支并优雅处理未知类型。
使用方式:环境变量 ASCEND_WEBHOOK_SECRET 存签名密钥。注册为手动流程,无自助后台,需邮件 developers@useascend.com 提供组织、环境(sandbox/production)、所需事件与 HTTPS 端点 URL,Ascend 返回签名密钥。本地测试可用 npx hookdeck-cli listen 3000 ascend --path /webhooks/ascend,无需账号,首次运行自动创建访客账户并提供本地隧道与请求检查界面。示例见 examples/express/、examples/nextjs/、examples/fastapi/。建议配合 webhook-handler-patterns 处理幂等、错误处理与重试。
限制:资料未提供具体收费、价格、性能数据或官方 SDK;签名验证必须保留原始请求体。