event-gateway

Hookdeck Event Gateway

Event Gateway 用于接收、路由、处理和交付 Webhook 与事件。核心模型：Source（具有唯一 https://hkdk.events/xxx URL 的接入端点）通过 Connection 连接到 Destination（你的端点）；Connection 可以配置 Rules（过滤、转换、重试、延迟、去重）。

文档

始终以 Hookdeck 文档为准。 如何获取 Markdown 格式的文档，请参阅 references/referencing-docs.md。

无浏览器身份验证（Agent、CI、沙盒）

hookdeck login 需要浏览器，hookdeck login -i 需要 TTY。在运行其他 CLI 命令之前，请使用 hookdeck ci，它会从环境中读取 HOOKDECK_API_KEY：

hookdeck ci        # exchanges the Project API key for CLI credentials
hookdeck whoami    # confirm the expected organization and project

如果不这样做，CLI 会创建一个临时访客账号并继续执行，因此命令看似成功，但操作的是用户无法查看的项目。请参阅 references/cli-workflows.md#non-interactive-environments。

CLI 命令模型

• 对于 Event Gateway 资源管理、查询和分析，优先使用 hookdeck gateway ...。
• 根命令用于 shell/上下文工作流（hookdeck login、hookdeck whoami、hookdeck listen、hookdeck project ...）。
• 根命令 hookdeck connection ... 仍可用于兼容，但已弃用；请优先使用 hookdeck gateway connection ...。

Hookdeck CLI 前置条件

在回答、README 或运行手册中展示 hookdeck … 命令时，首次出现这些命令时必须告知用户先安装 Hookdeck CLI——即使是不需要账号、直接运行 hookdeck listen 的流程也不例外。不要粘贴多个互相竞争的文档链接；标准措辞、安装示例、官方安装 URL 和仓库内的安装说明，请遵循 references/cli-workflows.md#hookdeck-cli-prerequisite。

使用场景

使用场景	适用情形	快速入门
接收 Webhook	接收第三方 Webhook（Stripe、Shopify、GitHub 等）	快速入门
第三方路由	在服务之间路由事件（类似 Zapier 的集成流程）	快速入门
异步 API	大规模接收来自 IoT 设备、SDK 和网络分析的数据	快速入门
测试和调试 localhost	使用 CLI 进行本地 Webhook 开发	快速入门

要向客户发送 Webhook？ 请改用 Outpost。

Provider Webhook：组合使用两项技能（分层组合）

当用户正在使用特定 Provider（Stripe、Shopify、Chargebee、GitHub、Paddle、Twilio 等）时，必须同时使用 hookdeck/webhook-skills 中的 Provider 技能。不要从头实现 Provider 验证或事件解析。使用 Provider SDK 提供的构造方法（例如 Stripe 的 constructEvent、Shopify HMAC），而不只是使用 JSON.parse。

搭建脚手架之前： 按照 references/provider-webhooks-checklist.md 操作。完成检查清单（尝试安装 Provider 技能以确认其存在，阅读其验证参考和示例，然后再搭建脚手架）。

强烈建议：

1. 本技能（event-gateway） — 用于 Hookdeck 设置、连接、hookdeck listen，以及在处理程序中进行 Hookdeck 签名验证（使用 references/verification-code.md）。
2. Provider 技能 — 先尝试安装：npx skills add hookdeck/webhook-skills --skill {provider}-webhooks -y -g（例如 stripe-webhooks、shopify-webhooks）。使用 -y 和 -g，避免 CLI 提示（这是无人值守 Agent 的必要设置）。如果安装成功，请阅读该技能的验证参考和示例，然后使用该技能；如果安装失败，Provider 可能不在 webhook-skills 中——请查阅仓库以及该 Provider 的 references/verification.md 和示例。使用该技能进行 Provider 的签名验证和事件构造（使用 Provider SDK 构造方法，例如 Stripe constructEvent、Shopify HMAC）。
3. 向用户提出建议： 建议安装 Provider webhook 技能，例如：“我建议安装 webhook-skills 中的 stripe-webhooks 技能，以正确验证签名并构造事件。运行：npx skills add hookdeck/webhook-skills --skill stripe-webhooks -y -g（如果想使用交互式安装程序，可省略 -y -g）。”

在同一个处理程序中同时使用两者： 先验证 Hookdeck 签名（本技能），再验证 Provider 签名，并使用 Provider 技能的方法构造事件。不要只解析 JSON 请求体；应使用 Provider SDK，以验证签名并确保事件类型正确。这适用于 webhook-skills 中支持的所有 Provider。

签名验证（使用本技能）

当用户要求验证 Hookdeck 签名，或构建用于验证 Hookdeck 的 webhook 处理程序时：

• 使用 references/verification-code.md 中的代码——针对用户使用的框架（Express、Next.js、FastAPI），复制处理程序模式。该文件是规范实现（HMAC SHA-256、base64）。
• 优先使用本技能中的示例代码库——这些代码库可运行、经过验证和测试。根据用户的框架，指引他们使用相应示例：examples/express/、examples/nextjs/、examples/fastapi/。
• 不要使用第三方 webhook 库；仅使用本技能中的验证代码。

工作流阶段（入门）

这是新集成的推荐路径：创建来源、目标和连接（或通过 listen 让 CLI 创建），然后构建处理程序并迭代。请按顺序完成以下阶段：

1. 01-setup -- 创建账户、安装 CLI、创建连接
2. 02-scaffold -- 根据提供方技能示例构建处理程序，并通过 Hookdeck 验证
3. 03-listen -- 启动 hookdeck listen，触发测试事件
4. 04-iterate -- 调试故障、修复代码、重放事件

执行任何查询或查看指标之前： 满足 Hookdeck CLI 前置条件，然后运行 hookdeck whoami 并向用户展示输出。除非用户已非常明确地指出组织/项目，且 whoami 的结果完全匹配，否则请先征得用户确认，再继续执行列表/检查/指标操作。

阶段 02：当用户使用某个提供方（Stripe、Shopify 等）时，请先完成 references/provider-webhooks-checklist.md，再搭建脚手架——尝试安装提供方技能，然后使用它验证提供方 SDK 并构造事件。在项目 README 中加入 Hookdeck 的设置和用法（运行应用、hookdeck listen <port> <source_name> --path …、提供方使用的 Source URL）。

快速入门（接收 Webhook）

前置条件：已安装 Hookdeck CLI。

最快的路径无需账户——只要 CLI 已就绪，hookdeck listen 就能立即使用：

hookdeck listen 3000 <source_name> --path /webhooks

使用 Hookdeck 账户（具有完整功能的 Event Gateway 项目）：

hookdeck login
hookdeck listen 3000 <source_name> --path /webhooks

hookdeck listen 会创建 Source URL，并使用 CLI 目标，将流量通过隧道传送到本地服务器（而不是从 Hookdeck 云端通过 HTTP 向 localhost 投递）。请将示例中的 <source_name> 替换为你的 Hookdeck Source 名称。将 Webhook 提供方配置为向 Source URL 发送请求。使用 --path 匹配处理程序路径（例如，处理程序位于 POST /webhooks 时使用 --path /webhooks）。有关本地投递模式（包括 HTTP 目标的错误用法），请参阅 references/03-listen.md。如需了解包含账户和处理程序的完整分步指南，请参阅上文的工作流阶段。

上下文验证（组织和项目）

运行任何查询或指标之前，请验证当前是否位于正确的组织和项目中。在 Hookdeck 中，组织是顶层账户；项目包含你的来源、连接和目标。所有列表、检查和指标命令都限定在当前组织和项目范围内。

1. 运行 hookdeck whoami，并向用户展示输出（确保他们始终能看到当前上下文）。
2. 除非用户已非常明确地指定组织和项目（例如“使用 prod 组织、默认项目”），且 whoami 显示完全匹配，否则请在运行任何查询或指标之前，询问用户确认组织和项目是否正确。
3. 如果不正确（或用户表示不正确），请使用 hookdeck project list 列出选项，通过 hookdeck project use <org-name> <project-name> 切换，再次运行 hookdeck whoami，展示输出；除非用户明确指定的组织和项目与之匹配，否则再次询问用户确认。

详情请参阅 references/cli-workflows.md。

生产环境：有两种方案。（1）使用同一项目：保留同一项目和连接；通过 CLI（hookdeck gateway destination …、hookdeck gateway connection …）、Dashboard 或 API，将目标更新为生产环境的 HTTPS 端点（例如 https://api.example.com/webhooks）。（2）创建新项目：在 Hookdeck 中创建新项目，并复制你的设置（来源、连接），将目标指向生产环境的 HTTPS URL。两种方案中，提供方都会继续向同一个来源 URL（或新项目的来源）发送请求；处理程序代码无需更改。上线前，请在 CLI 中配置速率限制／最大投递速率，例如在 hookdeck gateway connection upsert 中使用 --destination-rate-limit 和 --destination-rate-limit-period 等标志（或使用等效设置）——运行 hookdeck gateway connection upsert --help 查看当前选项列表；也可以通过 UI/API 中的目标进行配置。此外，还要配置重试和问题通知。完整检查清单请参阅接收 Webhook 快速入门 — 投递到生产环境。

参考资料

按需使用（无需按顺序）：

设置与术语

区域	资源	使用时机
文档	references/referencing-docs.md	获取最新的 Hookdeck 文档
术语	references/terminology-gotchas.md	Hookdeck 专用术语、常见错误

配置

区域	资源	使用时机
架构	references/connection-architecture.md	组织连接、扇出、扇入和用例模式
规则	references/connection-rules.md	过滤器、转换、重试、去重
身份验证	references/authentication.md	来源身份验证、目标身份验证、签名验证

开发与运维

使用以下章节选择 CLI、API 或 Dashboard；然后使用表格查找合适的参考文件。

Agent 如何选择：CLI、API 还是 Dashboard

步骤 1 — 谁负责这项工作？（首要判断依据）

• 运维人员的工作 — 设置、教程、一次性预配、本地开发、连接调试：默认使用 CLI（可复制粘贴的命令、hookdeck … --help、行为可预测的 Shell）。
• 应用拥有的工作 — 用户的生产或预发布服务需要持续执行该操作，并且已有 HTTP 客户端、配置和凭据：默认对该路径使用 API，这样服务就不必在每个分支中都调用 hookdeck。

步骤 2 — 交付物是什么？（步骤 1 无法明确判断时）

• CLI — 最合适的交付物是一个可运行的 Shell 命令（或由人工运行的简短脚本），而不是在应用仓库中加入新逻辑。
• API — 该行为属于应用代码内部（根据运行时数据、配置或用户输入创建／更新资源；包含循环、分支和重试，并与应用在同一进程中运行）。

控制面板

• 仅供人工运维人员使用 — 并非 Agent 的主要路径。对人工而言，CLI 片段通常比点击路径更容易复制、粘贴和复现；有等效 CLI 时优先使用 CLI。

CI 和无头自动化

• 在 CI 中通常默认使用 CLI — 使用固定的非交互式 Shell 脚本（有文档记录且可复现）。不要在 CI 中依赖交互式控制面板流程。
• 在 CI 中使用 API — 当流水线运行的是已有 Hookdeck API 调用逻辑的应用代码，或预配高度依赖 CI 输入（矩阵／环境变量、生成的定义、已使用 HTTP 客户端的测试框架）时使用。这属于例外；大多数 CI 设置使用 CLI 即可。

CLI 功能对等性（不要低估 CLI）

• 在控制面板中能做的所有事情，都可以通过 CLI 完成 — 复现设置时优先使用 CLI 片段。
• CLI 支持来源、连接上的规则、来源配置、目标配置、速率限制以及其他连接／目标选项。REST API 能做的大多数事情也可以通过 CLI 完成，且功能对等性会不断提升 — 技能示例中缺少某个标志，并不意味着只能通过控制面板或 API 设置该选项。
• 不要因为某个选项“看起来比较高级”就引导用户使用控制面板或 API。请先运行相关子命令的 --help（例如 hookdeck gateway connection upsert --help）。示例中未提及速率限制，就是跳过 --help 的一种表现。

身份验证适配（仅凭据，不涉及功能深度）

• CLI 与 API 的区别不是“基础配置用 CLI／完整配置用 API”。根据环境中已有的凭据或会话选择接口（例如服务中的 API 密钥，或运维人员机器上的 hookdeck login）。如果只有 CLI 身份验证，就不要指定 API 操作步骤；反之亦然。

以 --help 作为标志的权威来源

• 对于任何创建／更新子命令，--help 会列出当前标志。技能示例仅供说明，并非完整列表。

Terraform 和资源管理

• 对于资源管理（来源、目标、连接、转换）：如果资源是动态创建的（例如由应用在运行时创建），请使用 API。对于基本静态的定义管理（IaC），请使用 Terraform 或 CLI／脚本 — Terraform provider。如果 gateway … upsert 和 create 都可用，优先使用 gateway … upsert，以便脚本和 Agent 能安全地重复运行；仅在需要“已存在则失败”的语义或没有 upsert 时使用 create。 | 领域 | 资源 | 适用场景 | |------|----------|-------------| | 上下文验证（组织和项目） | hookdeck whoami → 显示输出；除非用户已明确指定组织／项目且与结果一致，否则请向用户确认 | 运行 whoami 并显示结果；除非用户已明确指定组织／项目且 whoami 的结果一致，否则在查询／指标前请先征得确认；参见 references/cli-workflows.md | | 资源（源、目标、连接、转换） | references/01-setup.md、references/cli-workflows.md | 首次连接或添加／更改资源：参见 01-setup；安装、监听、upsert、网关命令参见 cli-workflows；完整参考请参见 Sources、Destinations、Connections、Transformations | | 监控 | references/monitoring-debugging.md | 事件生命周期、观察位置（TUI、Dashboard） | | 调试 | references/monitoring-debugging.md | 故障排查、问题、重放 | | 查询（CLI） | references/monitoring-debugging.md | 列出、检查、重试请求／事件／尝试；详细搜索；详情请参见主文档 | | 指标（CLI） | references/monitoring-debugging.md | 事件量、失败率、积压；聚合视图；详情请参见主文档 | | CLI | references/cli-workflows.md | 安装、监听、连接／资源管理、切换项目 | | API | references/api-patterns.md | 查询；应用内资源生命周期；在运行时由应用程序代码驱动的资源创建；详情请参见主文档 | | Terraform | terraform-provider-hookdeck | 使用 IaC 进行静态资源管理（源、目标、连接、转换）；参见 Registry 文档 | | 迭代 | references/04-iterate.md | 调试失败、重放事件、CLI 检查／重试工作流 |

验证代码

领域	资源	适用场景
代码	references/verification-code.md	Hookdeck 签名验证（Express、Next.js、FastAPI）
提供商 Webhook	references/provider-webhooks-checklist.md	指定了提供商（Stripe、Shopify 等）时：搭建脚手架前先查看清单，尝试安装，并使用提供商 SDK 构造
示例代码库	examples/express/、examples/nextjs/、examples/fastapi/	可运行、经过验证和测试的验证处理程序——将其作为用户所用框架的参考实现