用途:该技能面向 GoCardless(银行扣款与循环支付平台)的 Webhook 接入,用于接收并验证其回调,排查 Webhook-Signature 校验失败,以及处理支付确认/失败、授权取消、打款到账等事件。
主要能力:GoCardless 以 events 数组批量发送事件(单次最多 250 条),使用 Webhook-Signature 头携带 HMAC-SHA256 签名。技能说明签名细节:头值为 64 位小写十六进制摘要,无 X- 前缀、无 sha256= 前缀;密钥为 Dashboard 中的 webhook endpoint secret,需按 UTF-8 原样使用,不要因其形似 base64url 而解码;比较需使用恒定时间比较。整批接受后返回 204 No Content,非 2xx(如 498)视为投递失败。GoCardless 不自动重试,重投需手动调用 POST /webhooks/{id}/actions/retry;投递为至少一次,因此处理器需按 event.id 保持幂等。
使用方式:Node.js 可用官方 gocardless-nodejs SDK 的 parse() 校验签名并返回 events 数组,签名不匹配时抛出 InvalidSignatureError;无 SDK 的语言(如 Python/FastAPI)可手动用 hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() 与 hmac.compare_digest 校验。必须基于原始请求体校验,先解析 JSON 再序列化会改变字节导致签名失效。环境变量为 GOCARDLESS_WEBHOOK_SECRET。本地调试可运行 npx hookdeck-cli listen 3000 gocardless --path /webhooks/gocardless(FastAPI 示例用端口 8000),无需账号。
适用场景:搭建 Express、Next.js、FastAPI 等 Webhook 处理器,处理 payments、mandates、payouts、refunds、subscriptions 等资源类型的常见动作。
限制:资料未提供具体收费、价格与平台支持范围等信息;签名方案说明基于 2026-08 的沙箱验证与官方 SDK,官方文档未明确写出算法名称。