SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场event-gateway

event-gateway

部署与运维

查看项目

更新于 10-15 13:51

技能介绍

用途

Hookdeck Event Gateway 用于接收、路由、处理和投递 webhook 与事件。其核心模型是：Source（带唯一 https://hkdk.events/xxx 地址的接收端点）通过 Connection 连接到 Destination（你的端点），Connection 可附加 Rules（filter、transform、retry、delay、deduplicate）。

本技能用于 Hookdeck 的环境配置、连接管理、hookdeck listen 本地调试，以及在处理程序中校验 Hookdeck 签名。Hookdeck 官方文档为唯一事实来源，可参考 references/referencing-docs.md 获取 markdown 文档。

主要能力

  • 接收第三方 webhook（Stripe、Shopify、GitHub 等）
  • 在服务之间路由事件（类似 Zapier 的集成流）
  • 面向 IoT 设备、SDK、Web 分析的大规模异步 API 事件摄取
  • 通过 CLI 进行本地 webhook 开发与调试
  • 签名校验（HMAC SHA-256、base64），提供 Express、Next.js、FastAPI 示例
  • 与 provider webhook 技能分层组合：先校验 Hookdeck 签名，再使用 provider SDK 校验服务商签名并构造事件

使用方式

无浏览器环境认证（Agent、CI、沙箱）

hookdeck login 需要浏览器，hookdeck login -i 需要 TTY。应使用 hookdeck ci，从环境变量读取 HOOKDECK_API_KEY：

hookdeck ci # 用 Project API key 换取 CLI 凭证 hookdeck whoami # 确认预期的组织与项目

若不执行此步骤，CLI 会创建临时访客账号并继续运行，命令看似成功但作用于用户看不到的项目。

CLI 命令模型

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

CLI 前置条件

只要在回答、README 或 runbook 中出现 hookdeck … 命令，首次出现时应提示用户先安装 Hookdeck CLI，即使是无需账号、直接使用 hookdeck listen 的流程。

快速开始（接收 webhook）

前置条件：已安装 Hookdeck CLI。

无需账号的最快路径：

hookdeck listen 3000 <source_name> --path /webhooks

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

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

hookdeck listen 创建 Source URL 并使用 CLI destination，将流量隧道传输到本地服务器（而非从 Hookdeck 云到 localhost 的 HTTP 投递）。将 <source_name> 替换为你的 Hookdeck Source 名称，配置 webhook provider 发送到该 Source URL，使用 --path 匹配处理程序路径。

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

在运行任何查询或指标前，应验证当前组织和项目正确。在 Hookdeck 中，organization 是顶层账号，project 存放 sources、connections 和 destinations。运行 hookdeck whoami 并向用户展示输出；除非用户已明确指定组织与项目且 whoami 完全匹配，否则应请用户确认后再执行查询或指标。

工作流阶段

推荐路径：01-setup（创建账号、安装 CLI、创建连接）→ 02-scaffold（基于 provider 技能示例与 Hookdeck 校验构建处理程序）→ 03-listen（启动 hookdeck listen，触发测试事件）→ 04-iterate（调试失败、修复代码、重放事件）。

阶段 02 中，当用户使用特定 provider（Stripe、Shopify 等）时，须先完成 references/provider-webhooks-checklist.md，尝试安装 provider 技能，再使用其进行 provider SDK 校验与事件构造。

Provider webhook 分层组合

当用户使用特定 provider（Stripe、Shopify、Chargebee、GitHub、Paddle、Twilio 等）时，还应使用 hookdeck/webhook-skills 中对应的 provider 技能，不要从零实现 provider 校验或事件解析。建议安装：

npx skills add hookdeck/webhook-skills --skill {provider}-webhooks -y -g

在同一处理程序中先校验 Hookdeck 签名（本技能），再使用 provider 技能方法校验 provider 签名并构造事件，不要只解析 JSON。

生产环境

两种方案：(1) 同一项目：保持相同项目与连接，将 Destination 更新为生产 HTTPS 端点（如 https://api.example.com/webhooks）；(2) 新项目：新建项目并复制设置，Destination 指向生产 HTTPS URL。两种情况下 provider 都继续发送到同一 Source URL，处理程序代码不变。上线前应通过 CLI（如 hookdeck gateway connection upsert 的 --destination-rate-limit、--destination-rate-limit-period 等标志）或 UI/API 配置限流，并配置重试和问题通知。

接口选择：CLI、API 还是 Dashboard

  • 运维工作（设置、教程、一次性配置、本地开发、调试连接）：默认 CLI
  • 应用自有工作（生产/预发服务持续执行、已有 HTTP 客户端和凭证）：默认 API
  • Dashboard：仅供人工操作，不是 Agent 的主要路径
  • CI 与无头自动化：默认 CLI；若流水线运行已调用 Hookdeck API 的应用代码，则用 API

CLI 与 Dashboard 功能对等，不要因某选项“看起来高级”就引导用户使用 Dashboard 或 API，应先运行对应子命令的 --help。--help 是标志的权威来源。

资源管理与 Terraform

资源管理（sources、destinations、connections、transformations）：动态创建时用 API；静态定义（IaC）时用 Terraform 或 CLI/脚本。当 upsert 和 create 都存在时优先 upsert，以便脚本和 Agent 安全重跑。

签名校验

当用户要求校验 Hookdeck 签名或构建校验 Hookdeck 的处理程序时：

  • 使用 references/verification-code.md 中的代码（HMAC SHA-256、base64），按用户框架复制处理程序模式
  • 优先使用本技能中的可运行示例代码库：examples/express/、examples/nextjs/、examples/fastapi/
  • 不要使用第三方 webhook 库

适用场景

  • 接入第三方 webhook（Stripe、Shopify、GitHub 等）
  • 服务间事件路由
  • 大规模异步 API 事件摄取
  • 本地 webhook 开发与调试
  • 需要同时校验 Hookdeck 与 provider 双重签名的处理程序

限制

  • hookdeck login 需要浏览器，hookdeck login -i 需要 TTY；无浏览器环境必须使用 hookdeck ci
  • 根 hookdeck connection ... 命令已弃用
  • 向客户发送 webhook 应使用 Outpost 而非本技能
  • 不得从零实现 provider 签名校验，须使用 provider SDK 的构造方法
  • 文档未提供的具体价格、收费、平台支持范围等信息暂未提供