# Hookdeck 事件网关事件网关接收、路由、处理和传递 Webhook 和事件。核心模型：**[Source]()**（具有唯一`https://hkdk.events/xxx` URL的摄取端点）通过**[Connection]()**连接到**[Destination]()**（您的端点） [规则]()（过滤、转换、重试、延迟、重复数据删除）。 ## 文档始终参考 Hookdeck 文档作为事实来源。请参阅 [references/referencing-docs.md]() 了解如何以 Markdown 形式获取文档。 ## 用例使用案例 |何时使用 |快速入门 ---|---|--- **接收网络钩子** |摄取第三方 Webhook（Stripe、Shopify、GitHub 等）| [快速入门]() **第三方路由** |服务之间的路由事件（类似 Zapier 的集成流程）| [快速入门]() **异步 API** |从 IoT 设备、SDK、网络分析大规模事件摄取 | [快速入门]() **测试和调试本地主机** |使用 CLI 进行本地 Webhook 开发 | [快速入门]() > **向客户发送 webhook？** 使用 [Outpost]()。 ## Provider webhooks：同时使用两种技能（分层组合）当用户与**特定提供商**（Stripe、Shopify、Chargebee、GitHub、Paddle、Twilio 等）合作时，您**还必须**使用 [hookdeck/webhook-skills]() 中的提供商技能。不要从头开始实施提供者验证或事件解析。使用提供商 SDK 提供的 **构造（例如 Stripe 的 `constructEvent`、Shopify HMAC），而不仅仅是 `JSON.parse`。 **搭建脚手架之前：**遵循 [references/provider-webhooks-checklist.md]()。完成清单（尝试安装提供者技能以验证其存在，阅读其验证参考和示例，然后阅读脚手架）。 **强有力的指导：** 1. **此技能（事件网关）** - 将其用于处理程序中的 Hookdeck 设置、连接、`hookdeck 监听`和 **Hookdeck 签名验证**（使用 [references/verification-code.md]()）。 2. **提供者技能** — 首先尝试安装：`npx Skills add hookdeck/webhook-skills --skill {provider}-webhooks`（例如`stripe-webhooks`、`shopify-webhooks`）。如果安装成功，则使用已安装的技能；如果失败，则提供程序可能不在 webhook-skills 中 - 查找 [repo]() 和提供程序的 `references/verification.md` 和示例。使用该技能进行提供商的**签名验证和事件构建**（提供商 SDK 构建，例如 Stripe `constructEvent`、Shopify HMAC）。 3. **向用户推荐：** 建议安装provider webhook技能，例如“我建议从 webhook-skills 安装 stripe-webhooks 技能，以进行正确的签名验证和事件构造。运行：`npx Skills add hookdeck/webhook-skills --skill stripe-webhooks`。” **在同一个处理程序中使用两者：** 首先验证 Hookdeck 签名（此技能），然后验证提供者签名并使用提供者技能的方法构造事件。不要只解析 JSON 正文；使用提供商 SDK 来验证签名并正确输入事件。这适用于 webhook-skills 中所有支持的提供程序。 ## 签名验证（使用此技能）当用户要求验证 Hookdeck 签名或构建验证 Hookdeck 的 Webhook 处理程序时： * **使用[references/verification-code.md]()中的代码** — 复制用户框架（Express、Next.js、FastAPI）的处理程序模式。该文件是规范实现（HMAC SHA-256，base64）。 * **更喜欢本技能中的示例代码库** - 它们是可运行的、经过验证和测试的。将用户指向其框架的正确位置：[examples/express/]()、[examples/nextjs/](), [examples/fastapi/]()。 * 不使用第三方webhook库；仅使用此技能中的验证码。 ## 工作流程阶段（入门）这是新集成的推荐路径：创建源、目标和连接（或让 CLI 通过“listen”创建它们），然后构建处理程序并进行迭代。按顺序执行以下阶段： 1. **[01-setup]()** \-- 创建帐户，安装 CLI，创建连接 2. **[02-scaffold]()** \-- 从提供者技能示例构建处理程序 + Hookdeck 验证 3. **[03-listen]()** \-- 启动`hookdeck Listen`，触发测试事件 4. **[04-iterate]()** \-- 调试失败、修复代码、重播事件 > **在任何查询或指标之前：** 运行 `hookdeck whoami` 并向用户显示输出。除非用户非常清楚地识别了 org/project 和 whoami 完全匹配，否则请在继续列表/检查/指标之前要求他们确认。阶段 02：当用户与提供商（Stripe、Shopify 等）合作时，完成 [references/provider-webhooks-checklist.md]() **before** 脚手架 - 尝试安装提供商技能，然后将其用于提供商 SDK 验证和事件建设。在项目自述文件中包含 Hookdeck 设置和使用（运行应用程序、带有 `--path` 的 `hookdeck Listen`、提供程序的源 URL）。 ## 快速入门（接收 Webhooks）无需帐户 - `hookdeck Listen` 立即生效： brew install hookdeck/hookdeck/hookdeck # 或: npm i -g hookdeck-cli hookdeck 听 3000 --path /webhooks 使用 Hookdeck 帐户（具有完整功能的事件网关项目）：挂钩甲板登录 hookdeck 听 3000 --path /webhooks CLI 创建一个源 URL、一个指向 `localhost:3000` 的目标以及链接它们的连接。配置您的 Webhook 提供程序以发送到源 URL。使用 `--path` 来匹配您的处理程序路径（例如，当您的处理程序位于 `POST /webhooks` 时使用 `--path /webhooks`）。要了解帐户和处理程序的完整分步（创建连接、脚手架、监听、迭代），请遵循上面的 **工作流程阶段**。 ## 上下文验证（组织和项目） **在运行任何查询或指标之前**，请验证您处于正确的[组织和项目]()。在 Hookdeck 中，**组织**是顶级帐户； **项目**包含您的来源、连接和目的地。所有列表、检查和指标命令的范围仅限于当前组织和项目。 1. 运行 `hookdeck whoami` 并**向用户显示输出**（以便他们始终看到当前上下文）。 2. **除非**用户已经非常清楚地识别了组织和项目（例如“使用 prod org，默认项目”）并且 whoami 显示了 **完全匹配** ，请要求他们在运行任何查询或指标之前确认这是正确的组织和项目。 3. 如果错误（或用户这么说），则使用 `hookdeck project list` 列出选项，使用 `hookdeck project use

` 进行切换，再次运行 `hookdeck whoami`，显示输出，并且 — 除非有明确的用户指定匹配 — 要求用户再次确认。有关详细信息，请参阅 [references/cli-workflows.md]()。 **生产：** 两种选择。 **(1) 相同项目：** 保持相同的项目和连接；通过 [仪表板]() 或 [API]() 将 [Destination]() 更新为您的生产 HTTPS 端点（例如 `https://api.example.com/webhooks`）。 **(2) 新项目：** 在 Hookdeck 中创建一个 [新项目]() 并复制您的设置（源、连接），其中目标指向您的生产 HTTPS URL。在这两种情况下，提供者都会不断发送到相同的源 URL（或新项目的源）；处理程序代码未更改。在上线之前，请考虑：**速率限制/最大传送速率**（[目的地]()）、**配置重试**（[重试]()）和**问题通知**（[问题触发器]()、[问题和通知]())。 Hookdeck 文档是事实的来源；请参阅[接收 webhooks 快速入门 - 交付到生产]() 以及链接的目标、重试和问题触发器文档，了解完整的生产清单。 ## 参考资料根据需要使用（不按顺序）： ### 设置和术语面积 |资源 |何时使用 ---|---|--- 文档 | [references/referencing-docs.md]() |获取实时 Hookdeck 文档条款 | [references/terminology-gotchas.md]() | Hookdeck 特定术语、常见错误 ### 配置面积 |资源 |何时使用 ---|---|--- 建筑| [references/connection-architecture.md]() |构建连接、扇出、扇入、用例模式规则| [references/connection-rules.md]() |过滤、转换、重试、重复数据删除认证| [references/authentication.md]() |源认证、目的地认证、签名验证 ### 开发与运营根据任务引导自己找到正确的资源。 **首先使用 CLI 进行探索**并执行简单任务；然后当事情更复杂时选择 API 或 Terraform。 CLI 对于任务和某些分析来说是一个很好的初步接触；也可以使用API进行查询。 **任务和简单脚本**（来自 shell 的单个命令或简短的多命令工作流程）**→ 使用 CLI。** **复杂的脚本、应用程序和自动化 → 使用 API。** 如有疑问，请从 CLI 开始探索。对于**资源管理**（源、目的地、连接、转换）：在**动态**创建资源时使用**API**（例如，在运行时从应用程序）；使用 **Terraform** 或 CLI/脚本进行 **有效静态** 定义管理 (IaC) — [Terraform 提供程序]()。有关执行查询、指标或检查（任一路径）的详细信息，请参阅主要文档。面积 |资源 |何时使用 ---|---|--- **上下文验证**（组织和项目）| `hookdeck whoami` → **显示输出** ;与用户确认，除非他们明确指定了组织/项目并且它匹配 |运行 whoami 并显示结果；除非用户明确标识组织/项目和 whoami 匹配，否则在查询/指标之前要求确认；请参阅 [references/cli-workflows.md]() **资源**（源、目的地、连接、转换）| [references/01-setup.md](), [references/cli-workflows.md]() |首次连接或添加/更改源、目的地、连接、转换：01-setup 用于初始设置；用于 CLI 创建/更新插入的 cli 工作流程； [源]()、[目标]()、[连接]()、[转换]() 以获得完整参考监控| [references/monitoring-debugging.md]() |事件生命周期，在哪里观察（TUI、仪表板）调试| [references/monitoring-debugging.md]() |疑难解答、问题、重播查询 (CLI) | [references/monitoring-debugging.md]() |列出、检查、重试请求/事件/尝试；详细搜索；主要文档了解详细信息指标 (CLI) | [references/monitoring-debugging.md]() |事件量、故障率、积压；聚合视图；主要文档了解详细信息命令行| [references/cli-workflows.md]() |安装、监听、连接/资源管理、项目切换应用程序接口 | [references/api-patterns.md]() |查询；构建应用程序； **动态**资源创建（例如应用程序在运行时创建源/连接）；复杂的脚本；主要文档了解详细信息地形 | [terraform-provider-hookdeck]() | **静态**资源管理（源、目的地、连接、转换）作为 IaC； [注册表文档]() 迭代| [references/04-iterate.md]() |调试失败、重播事件、CLI 检查/重试工作流程 ### 验证码面积 |资源 |何时使用 ---|---|--- 代码| [references/verification-code.md]() | Hookdeck 签名验证（Express、Next.js、FastAPI） **提供商网络钩子** | [references/provider-webhooks-checklist.md]() |当指定提供商（Stripe、Shopify 等）时：搭建脚手架之前的清单、尝试安装、使用提供商 SDK 构造 **示例代码库** | [examples/express/](), [examples/nextjs/](), [examples/fastapi/]() |可运行、经过验证、经过测试的验证处理程序 — 使用它们作为用户框架的参考实现

事件网关

包含技能