SuperAPI AI 工具集

airwallex-webhooks

测试与质量

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证 Airwallex Webhook,适用于搭建 Airwallex Webhook 处理器、调试 x-signature / x-timestamp 签名校验失败,以及处理 payment_intent.succeeded、refund.settled、payment_dispute.* 等事件。

主要能力:Airwallex 对每个 Webhook 使用 HMAC-SHA256 签名,请求携带两个头:x-timestamp(Unix 毫秒时间戳)与 x-signature(HMAC-SHA256 十六进制摘要)。签名消息为 x-timestamp 拼接原始请求体(时间戳在前),密钥为该端点唯一 secret。资料指出没有 Node SDK 辅助方法,需手动验证,且必须使用原始未修改的请求体,先验证再解析 JSON。校验时使用 crypto.createHmac('sha256', secret).update(timestamp).update(rawBody).digest('hex'),并用 crypto.timingSafeEqual 做常量时间比较。

常见事件:事件类型为点分命名空间,类型在 payload 的 name 字段(不是 type),资源在 data.object。包括 payment_intent.succeeded、payment_intent.requires_payment_method、payment_attempt.authorized、payment_attempt.paid、refund.settled、refund.failed、payment_consent.verified、payment_dispute.requires_response、payment_dispute.won / lost 等。

使用方式:环境变量 AIRWALLEX_WEBHOOK_SECRET=whsec_xxxxx,每个 Webhook URL 有各自独立的 secret。本地开发可用 npx hookdeck-cli listen 3000 airwallex --path /webhooks/airwallex 启动隧道,无需账号即可在本地检查与重放 Airwallex Webhook。完整处理器(路由接线、事件分发、测试)见 examples/express/、examples/nextjs/、examples/fastapi/。

限制与说明:资料未提供收费、价格、平台支持范围等信息。建议配合 webhook-handler-patterns 技能处理处理器顺序、幂等性、错误处理与重试逻辑;Airwallex 重试时使用稳定的事件 id,需做幂等处理。使用该技能时需在生成文件顶部添加指定注释。