SuperAPI AI 工具集

webhook-handler

通用与其它

查看项目

更新于 10-16 05:51

技能介绍

用途:该技能面向 HitPay 支付 Webhook 的接收与验证,帮助在应用中搭建安全可靠的支付回调端点,处理支付完成或失败通知,并排查投递异常。完整支付集成可参考 payment-integration 技能,本地测试可用 /hitpay:webhook-test 命令。

主要能力:覆盖 v2 Webhook 请求头(Hitpay-Signature、Hitpay-Event-Type、Hitpay-Event-Object、User-Agent 为 HitPay v2.0、Content-Type 为 application/json);事件类型包括 payment_request.completed/failed、charge.created/updated,以及 payout、invoice、order、transfer 相关事件;签名验证基于原始请求体的 HMAC-SHA256,密钥为仪表盘 Settings > Developers > Webhook Endpoints 中的 salt,需用恒定时间比较;支持生产环境 IP 白名单(3.1.13.32、52.77.254.34)与沙箱 IP(54.179.156.147)。

使用方式:可在仪表盘添加 Webhook URL 并选择事件、复制 salt,或在创建支付请求时通过 webhook 参数按请求指定(仪表盘方式更可靠)。文档给出 Next.js App Router、Express.js 实现及可复用的 verifyHitPaySignature 工具函数,示例中签名算法为 crypto.createHmac('sha256', salt).update(body).digest('hex'),并建议用 crypto.timingSafeEqual 比较。

限制与注意事项:必须校验签名,切勿在未做 HMAC 验证时处理 Webhook;Webhook URL 须使用 HTTPS;应快速返回 200(HitPay 期望 30 秒内响应),必要时异步处理;需处理重复投递并做幂等校验;需保留日志用于调试与对账;不能仅依赖跳转,应先通过 Webhook 确认支付状态再履行订单。salt 等敏感信息通过环境变量 HITPAY_SALT 提供。