SuperAPI AI 工具集

paystack-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:Paystack 是非洲支付平台,会通过 HTTP POST 把支付生命周期事件(扣款、转账、退款、订阅、发票、争议)以 JSON 负载发送到你的端点。本技能用于搭建 Paystack Webhook 处理程序、排查 x-paystack-signature 校验问题、以及处理各事件类型。

主要能力:讲解事件与负载结构;核心是签名校验。Paystack 用 HMAC-SHA512 对原始请求体签名(十六进制),放在 x-paystack-signature 头中,密钥即 API 使用的秘钥 sk_test_… / sk_live_…。官方 SDK 是无校验助手的通用 API 客户端,需手动实现。Node.js 可用 crypto.createHmac('sha512', secret).update(rawBody).digest('hex') 后用 crypto.timingSafeEqual 比较;Python 可用 hmac.new(secret.encode(), raw_body, hashlib.sha512).hexdigest() 配合 hmac.compare_digest。务必校验原始请求体,不要先 JSON.parse。

常见事件:charge.success、transfer.success/failed/reversed、refund.processed、subscription.create/disable、invoice.create/update/payment_failed、charge.dispute.create。事件类型在 JSON 体的 event 字段中。

环境变量:PAYSTACK_SECRET_KEY=sk_test_…,来源于 Dashboard → Settings → API Keys & Webhooks。测试与生产模式密钥分开,签名仅在对应模式下有效。

本地开发:npx hookdeck-cli listen 3000 paystack --path /webhooks/paystack

参考:references/overview.md、references/setup.md、references/verification.md;示例见 examples/express/、examples/nextjs/、examples/fastapi/。官方建议配合 webhook-handler-patterns 技能,并注意去重(按 event + data.id/data.reference)以免重复处理。