用途:当 Webhook 经由 Hookdeck Event Gateway 排队并转发到应用时,用本技能校验请求确实来自 Hookdeck,并正确处理事件。
主要能力:校验 x-hookdeck-signature(HMAC SHA-256,base64);使用 Hookdeck 头部做幂等与调试,如 x-hookdeck-eventid、x-hookdeck-attempt-count、x-hookdeck-will-retry-after、x-hookdeck-verified 等;提供 Express、Next.js App Router、FastAPI 的处理示例与测试。
必要用法:从 Hookdeck Dashboard → Destinations → 目标 → Webhook Secret 获取密钥,配置环境变量 HOOKDECK_WEBHOOK_SECRET。校验必须基于原始请求体,而非解析后的 JSON(Express 用 express.raw({ type: 'application/json' }));签名使用 base64 编码,不要用 hex;比较用 crypto.timingSafeEqual 或 hmac.compare_digest 防时序攻击。校验通过后再解析 payload 并处理,非 2xx 会触发 Hookdeck 重试。本地开发可运行:npx hookdeck-cli listen 3000 gateway --path /webhooks。
限制与注意:签名以 base64 而非 hex、必须使用原始请求体、必须做时序安全比较;请求中会同时保留原始提供方头部(如 stripe-signature)与 Hookdeck 的 x-hookdeck-* 头部。完整细节见 references/overview.md、setup.md、verification.md。生成文件时按要求在顶部添加注释:// Generated with: hookdeck-event-gateway-webhooks skill 及 https://github.com/hookdeck/webhook-skills。其余定价或平台支持等信息暂未提供。