SlingHook

slinghook CLI

将 SlingHook 服务捕获的 Webhook 转发到你机器上的服务，例如 localhost:3000。托管的 SlingHook 实例无法访问你的本地主机，因此 CLI 会像 stripe listen 一样，通过出站连接建立连接。

需要 Node 20.17+。

npm install -g slinghook

slinghook auth login --server https://slinghook.co.za
slinghook auth status          # who you're logged in as
slinghook endpoints            # list your endpoint UUIDs
slinghook mcp                  # MCP server for AI agents (see below)
slinghook listen <uuid> --forward http://localhost:3000/webhooks
# <uuid> can also be the catch URL you copied, e.g. https://slinghook.co.za/c/<uuid>

每条命令也可以使用简写 shk，例如 shk auth login 或 shk listen <uuid> --forward …。login、status 和 logout 也可以不带 auth 使用，和早期版本一样。

● Listening on endpoint 3f1c…
  Forwarding to http://localhost:3000/webhooks

14:02:11 POST   #1234 → 200 37ms sig:valid
14:02:15 POST   #1235 → ✗ Connection refused (is your local server running?) 2ms

工作原理

1. 身份验证。 slinghook login 的用法类似于 gh auth login。它会询问你想如何登录：

   • Web 浏览器。 CLI 会显示一次性代码（例如 BCDF-GHJK）并打开控制面板。在那里照常登录（使用密码、Google、GitHub、SAML 或双重身份验证），然后批准此代码。随后 CLI 会收到一个以你的计算机命名的新 API 令牌。该令牌适用于你批准它时所在的工作区。--web 会跳过提问。代码会在 15 分钟后过期。
   • 个人访问令牌。 在 用户设置 → API 令牌（/app/?settings=tokens）下创建一个令牌并粘贴。脚本和 CI 中可使用 slinghook login --with-token < token.txt、--token shk_…，或设置 SLINGHOOK_TOKEN。

   只会保存令牌，位置为 ~/.config/slinghook/config.json（模式为 0600）。服务端只存储该令牌的 SHA-256 哈希值。你可以在 用户设置 → API 令牌 下查看和撤销令牌。

2. 数据流。 listen 会通过 Authorization: Bearer <token> 打开 GET /v1/events/<uuid>。这与控制面板使用的 SSE 数据流相同。首次连接时，服务端会发送近期的 history，CLI 会跳过这些记录。它只转发新的 log 事件。

3. 重新连接。 服务端会按设计每隔约 55 秒关闭一次数据流。CLI 会使用 Last-Event-ID 重新连接，因此间隔期间到达的 Webhook 会按顺序投递一次。网络错误时，重试等待时间会从 1 秒逐渐增加到最多 30 秒。

4. 转发。 每个 Webhook 都会使用其原始方法、正文、查询字符串和请求头重新发送。Host 和 Content-Length 等逐跳请求头会被丢弃。签名请求头会保留，因此应用会正常执行验证。CLI 会添加 X-Webhook-Replay: true 和 X-SlingHook-Log-Id。投递会逐个进行，超时时间为 15 秒。捕获时已截断的负载会被跳过。 如果你的服务已关闭、超时，或返回 408、425、429 或 5xx，CLI 会再重试 3 次（分别等待 1 秒、2 秒和 4 秒），然后继续处理。后续 Webhook 会等待，因此仍会按顺序到达。--retries N 可更改重试次数（0 到 10）。

5. 报告。 每个结果都会提交到 POST /api/logs/<id>/replays，因此会显示在控制面板的重放历史记录中。使用 --no-report 可关闭此功能。

团队路由：一个提供商 URL，多位开发者

使用 Team 计划时，整个团队可以共享一个端点（Stripe 和 Shopify 只允许配置少数几个 Webhook URL），同时每个人仍可在自己的机器上收到各自的事件。认领属于你的事件，然后使用 --mine 监听：

# Events whose body has metadata.dev = "alice" go to Alice's localhost
slinghook listen <uuid> --forward http://localhost:3000/webhooks \
  --claim data.object.metadata.dev=alice

# Or claim by a header or query parameter
slinghook listen <uuid> --forward http://localhost:3000/webhooks --claim header:X-Dev=alice

--claim 会将你的认领条件保存到端点上（替换你之前的条件），并隐含启用 --mine。可重复使用它来设置多个条件。你也可以在控制面板的 端点设置 → 团队路由 中编辑认领条件，然后运行 listen --mine，而不使用 --claim。

使用 --mine 时，CLI 只会转发路由给你的事件，并且打开的数据流会将你计为在线。无人认领的事件会留在共享动态中，供所有人查看；除非端点设置为将这些事件分配给任一在线用户，此时它们会按轮询方式分配给运行 listen --mine 的用户。查看者可以观看，但不能认领事件。

请勿同时为同一端点运行 CLI 并启用控制面板的 Auto-Relay 开关，否则每个 Webhook 都会被投递两次。

混沌模式：你的处理程序是否具备幂等性？

Pro 和 Team 用户可以使用 slinghook chaos，将已保存的场景（或捕获的一条请求）发送给你的处理程序，模拟服务提供商的真实行为：

slinghook chaos <uuid> --forward http://localhost:3000/webhooks --scenario 12 \
  --check http://localhost:3000/debug/orders/count

每个事件会先发送一次（基线）。然后按顺序执行：

测试	发送内容	通过条件
duplicates	再次发送每个事件	2xx
concurrent	同时发送同一事件 3 次	全部为 2xx
out_of_order	按事件的逆序再次发送	2xx，或返回 409/425/429/503 以请求重试
malformed	将第一个请求体截成一半、留空，或替换为乱码	4xx
late_retry	在 --late-delay 秒后再次发送第一个事件	2xx

投递内容会按捕获时的原样发送，包括签名，但不带 X-Webhook-Replay 标头，这样你的处理程序会像处理服务提供商自己的重新投递一样处理这些请求。状态码无法体现重复的副作用，因此请通过应用中的 GET 检查状态（例如订单数量或余额），并使用 --check。基线之后以及每项测试之后都会读取该状态；任何变化都会导致该测试失败。

使用 --only duplicates,concurrent 选择测试。不指定 --scenario 运行，即可列出该端点的场景。报告会保存到控制面板（⌘K → “混沌模式”），测试失败时命令会以代码 1 退出，因此可在 CI 中运行。

MCP 服务：让你的 AI Agent 调试 Webhook

slinghook mcp 是一个 Model Context Protocol 服务。Claude Code、Cursor 和 VS Code 等编码 Agent 会在后台启动它，并以你的身份将 SlingHook 作为一组工具调用。告诉你的 Agent：“我的 Stripe Webhook 失败了，找出原因并修复它”，它就能完成整个 接收、调试、重放流程：

工具	功能	是否会更改内容？
list_endpoints	你的接收 URL，以及每个 URL 转发到的位置	否
list_events	已捕获 Webhook 的简短摘要（不含正文）。所有套餐均显示最新的 50 条；query 和 before_id 可搜索完整历史记录（Pro）	否
get_event	单个 Webhook 的完整内容：标头、查询参数、正文（过长的正文会被截断）	否
debug_signature	签名失败的原因，也可以使用候选密钥进行验证	否
replay_event	从你的机器向处理程序重新发送 Webhook，记录结果并返回判定：已修复、再次出错、仍然失败或仍然通过	是：实际投递
get_replay_result	重放历史记录和修复验证判定（Pro 套餐会显示两者的响应正文）	否
list_scenarios	某个端点上已保存的场景（按顺序排列的事件集）	否
run_scenario	从你的机器向处理程序重放场景的每一步，并报告每一步的结果（连续发送，或使用 keep_timing 保留记录的间隔，最多 5 秒；每分钟最多运行 3 次）	是：实际投递
generate_handler	根据真实事件生成类型定义、测试夹具和测试（TypeScript、Python、PHP 或 Go），供你据此构建处理程序。不会自行写入文件	否
compare_events	逐字段比较两个 Webhook 的差异（默认为同类型的上一条事件）	否
create_endpoint	新建接收 URL（名称相同则返回现有 URL；每个会话最多创建 5 个；请勿通过聊天传递密钥）	是：添加端点

每个事件在你的账户中都有一个编号（#12），显示在仪表板的信息流中。你可以用自然的方式向 Agent 指出事件，例如：“事件 12”“最新事件”“最新的 invoice.paid”，或使用提供商自己的 ID，例如 Stripe 的 evt_1Qx...。检查器中的 #12 菜单也会复制一条可直接使用的提示词。

在 slinghook login 后添加一次：

# Claude Code (macOS, Linux)
claude mcp add slinghook -- slinghook mcp

# Claude Code on Windows: npm installs slinghook as a .cmd file, which needs cmd /c
claude mcp add slinghook -- cmd /c slinghook mcp

其他客户端在 JSON 配置中使用相同的命令：

{ "mcpServers": { "slinghook": { "command": "slinghook", "args": ["mcp"] } } }

在 Claude Code 中，/mcp 会显示连接状态。由于 replay_event 工具被标记为会更改内容，Agent 在运行它之前会先征求同意。

安全防护：

• 重放仅限本地。 replay_event 只会向 localhost 和专用网络发送请求（10.x、172.16-31.x、192.168.x、host.docker.internal）。Webhook 正文由第三方写入，精心构造的正文可能试图诱使你的 Agent 将存储的载荷发送到其他位置。使用 slinghook mcp --allow-remote-targets 启动服务即可解除此限制。
• 速率限制。 每个 MCP 会话最多可调用工具 60 次，每分钟最多重放 10 次，因此循环运行的 Agent 会很快停止。
• 你的权限。 每次调用都会使用你的令牌，因此会遵循服务端规则：你的工作区、你的角色（查看者无法重放）和你的套餐。

该服务通过 stdin 和 stdout 使用 JSON-RPC，因此自身不会向 stdout 输出任何内容；启动提示会输出到 stderr。要查看协议，请通过管道传入请求：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | slinghook mcp

已知限制

• 正文会以文本形式通过 JSON 事件流传输，因此二进制载荷无法逐字节转发。
• 目前尚不支持重试。投递失败时会报告错误，你可以在仪表板中重放。

开发

在 SlingHook 仓库的本地副本中，运行 cd cli && npm link，即可将工作副本添加到 PATH；运行 npm test 可执行测试。

发布

更新 package.json 中的 version，然后在此文件夹中运行 npm publish。发布前会先运行测试（prepublishOnly），且软件包仅包含 bin/、src/、此 README 和 package.json。