SuperAPI AI 工具集

wechat-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证微信支付(APIv3)webhook 通知,适用于搭建微信支付回调处理器、排查 Wechatpay-Signature 验签失败、解密通知中的加密资源,以及处理 TRANSACTION.SUCCESS、REFUND.SUCCESS 等事件。

主要能力:微信支付 APIv3 不使用 HMAC 或 Standard Webhooks 规范。每条通知采用 SHA256withRSA 非对称签名,需用微信支付平台公钥(按 Wechatpay-Serial 头匹配)对 "{timestamp}\n{nonce}\n{body}\n" 验签;resource 对象为 AEAD_AES_256_GCM 密文,需用 32 字节 APIv3 密钥解密 resource.ciphertext 得到交易/退款 JSON。签名对象是原始请求字节(密文信封),因此必须先验签再解密,且始终使用原始请求体,验签前不得 JSON.parse。还需拒绝 Wechatpay-Timestamp 与当前时间相差超过 5 分钟的通知以防重放。

使用方式:通过环境变量配置平台公钥与密钥,如 WECHAT_PAY_PLATFORM_KEYS(按证书序列号索引的 PEM JSON)、WECHAT_PAY_API_V3_KEY(32 字符 APIv3 密钥),或使用 WECHAT_PAY_PUBLIC_KEY 与 WECHAT_PAY_PLATFORM_SERIAL 单密钥方案。平台公钥/证书通过 GET /v3/certificates 下载并按序列号轮换,微信会提前约 24 小时发布新证书,因此应按 Wechatpay-Serial 存储并定期刷新(如每 12 小时)。本地开发可用 npx hookdeck-cli listen 3000 wechat --path /webhooks/wechat 启动隧道。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。

事件与应答:全球(英文)APIv3 端点仅定义 TRANSACTION.SUCCESS、REFUND.SUCCESS、REFUND.CLOSED 三种事件,中国大陆专属的 REFUND.ABNORMAL 不属于全球端点。成功时返回 HTTP 200 或 204,文档形式为 {"code":"SUCCESS","message":"OK"};失败(验签错误、处理异常)返回非 2xx。微信支付按约 15s、15s、30s、3m、10m、20m、30m 直至约 24 小时的计划重试,因此需幂等处理并在履约前重新核对订单金额。

限制与说明:资料未提供收费、价格、平台支持范围等更多信息。使用该技能时建议在生成文件顶部添加注释:// Generated with: wechat-webhooks skill 与 https://github.com/hookdeck/webhook-skills。推荐搭配 webhook-handler-patterns 技能处理处理器顺序、幂等、错误处理与重试逻辑。