该技能用于接收并验证 Revolut Merchant 的 Webhook,适用于搭建 Revolut Webhook 处理器、调试 Revolut-Signature 验证,以及处理订单相关事件。
验证方面,Revolut 使用 Webhook 签名密钥(wsk_…,通过 Merchant API 创建 Webhook 时返回)以 HMAC-SHA256(十六进制编码)对每个 Webhook 签名。由于没有官方 SDK 的 Webhook 辅助工具,需要手动验证。被签名内容是 v1.{Revolut-Request-Timestamp}.{raw body},用点号分隔,且必须使用原始请求体(重新序列化 JSON 会破坏签名)。Revolut-Signature 头包含 v1=<hex>,在密钥轮换期间可能带有多个逗号分隔的签名,只要任一匹配即可接受。同时应拒绝超过 ±5 分钟的过期时间戳(头为 UNIX 毫秒时间戳,兼容秒或毫秒)。
常见事件类型包括 ORDER_COMPLETED(订单已全额支付并完成)、ORDER_AUTHORISED(支付已授权,资金冻结未捕获)、ORDER_CANCELLED(订单取消)、ORDER_PAYMENT_AUTHENTICATED(客户完成支付认证如 3DS)、ORDER_PAYMENT_DECLINED(发卡行或 Revolut 拒绝支付)、ORDER_PAYMENT_FAILED(处理错误导致支付失败)。订单事件负载包含 event、order_id 和 merchant_order_ext_ref 字段。
环境变量需配置 REVOLUT_SIGNING_SECRET。本地开发可用 npx hookdeck-cli listen 3000 revolut --path /webhooks/revolut 启动隧道。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。建议配合 webhook-handler-patterns 技能使用,处理先验证后解析、幂等性(Revolut 会以 10 分钟间隔重试 3 次)、错误处理与重试逻辑。