用途:接收并验证 Checkout.com 发送的 Webhook,适用于支付、拒付、欺诈、打款、发卡和身份验证等事件。面向当前 NAS/Workflows 平台,Webhook 在 Dashboard → Developers → Webhooks 配置,或通过 POST https://{prefix}.api.checkout.com/workflows 的 webhook action 创建。注意它并非 Checkout Page、CheckoutJoy、2Checkout/Verifone、Stripe Checkout 或 Shopify checkout。
主要能力:提供两种可选验证机制。Cko-Signature 为主,是对原始请求体做 HMAC-SHA256 后十六进制(Base16)编码,无 sha256= 前缀、无时间戳、无版本标签,仅一个签名;Authorization 为可选静态密钥,原样发送,无 Bearer 前缀,仅作补充。官方 SDK 不提供签名验证助手,需用 node:crypto 或 Python hmac+hashlib 自行计算。
使用方式:必须基于 HTTP 请求的原始字节计算 HMAC,不可 JSON.parse 后再 stringify;签名密钥按 UTF-8 原样使用,不可 base64/hex 解码,且它不是 sk_ 开头的 API 密钥。比较时先校验长度再用 timingSafeEqual。环境变量为 CHECKOUT_WEBHOOK_SIGNATURE_KEY(必需)与 CHECKOUT_WEBHOOK_AUTHORIZATION_KEY(可选)。本地开发可用 npx hookdeck-cli listen 3000 checkout-com --path /webhooks/checkout-com。
事件与限制:事件 id 形如 evt_…,用作幂等键;type 为 snake_case;时间字段因事件而异,需读 created_on ?? timestamp;amount 为最小货币单位。需在 10 秒内返回 2xx,最多重试 8 次,总窗口约 30 小时,至少保留事件 id 31 小时。投递为至少一次且顺序不保证,无握手或挑战请求,无时间戳与重放窗口。来源 IP 列表会变动,本技能不硬编码 IP。