deck-webhooks

Deck Webhooks 技能面向需要接收并验证 Deck（deck.co）事件流的开发者。Deck 是一个计算机使用代理 API，可代表用户登录网站；它通过事件目标推送事件，本技能专注于 webhook 类型目标：使用 Standard Webhooks 签名进行 HTTP POST 交付。

主要能力与使用方式：

1. 签名密钥管理：Deck 不签发签名密钥，webhook.secret 是可选且由调用方提供的，需自行生成（如使用 node 命令生成 whsec_ 前缀的 base64 随机字节），并在创建目标时传入，之后无法再次查看。没有密钥则无法验证交付。

2. 创建目标：通过 curl 调用 POST /v2/event-destinations 创建 webhook 目标，指定 URL、密钥和订阅事件。新目标初始为 pending_verification，端点返回 2xx 后激活并触发 event_destination.activated。

3. 签名验证：请求头包含 webhook-id、webhook-timestamp、webhook-signature（v1,<base64 HMAC-SHA256>，可能多个空格分隔）。签名内容为 {webhook-id}.{webhook-timestamp}.{raw body}，密钥为 secret 去掉 whsec_ 后 base64 解码的部分。推荐使用官方 SDK（npm/PyPI 的 standardwebhooks），其强制 5 分钟时间戳容差并采用恒定时间比较。示例代码展示了 JavaScript 和 Python 的验证方式，支持密钥轮换期间使用当前与先前密钥。

4. 事件信封：包含 id、object、type、data、created_at、request_id 等字段。type 是判别器（object.action）。无值字段可能为空字符串，workflow_run.* 有特殊处理。

5. 常见事件类型：包括 task_run.interaction_required（需用户输入，5 分钟窗口）、task_run.completed/failed、credential.verified/invalid、workflow_run 状态变化、storage.created、event_destination.activated/deactivated、test.ping 等。还列出了 agent.、source.、session.、task. 等更多事件。

6. 交互响应：对于 task_run.interaction_required，读取 data.interaction.fields 并调用 POST /v2/task-runs/{data.id}/interaction 提交输入。

7. 交付语义：需在 5 秒内返回 2xx，否则视为失败并重试；最多 10 次指数退避重试；至少一次交付，需按事件 id 去重；顺序不保证，需比较 created_at 丢弃过期更新；提供静态交付 IP 作为可选防御。

8. 环境变量：DECK_WEBHOOK_SECRET 必需，DECK_WEBHOOK_SECRET_PREVIOUS 可选用于轮换窗口。

9. 本地开发：可使用 Hookdeck CLI 监听本地端口，无需安装或账户；也可在 Deck 控制台使用 Test endpoint 查看负载。Deck 还支持原生 hookdeck 目标类型。

适用场景：需要集成 Deck 代理事件、处理任务交互（如 MFA 提示）、构建可靠 webhook 处理器、验证签名、轮换密钥等。限制：文档未指定密钥长度，部分事件细节可能需参考完整事件目录；需自行管理密钥和去重逻辑。

建议配合 webhook-handler-patterns 技能使用，涵盖处理器顺序、幂等性、错误处理和重试逻辑。