# 想在 ngrok 重放 webhook，就得完整存下客户数据

> Stripe CLI 无需公网 URL 就能转发事件；非开隧道不可时，要在第一个请求到来前设好限制。

原文: https://fdetimes.net/zh/tools/ngrok-webhook-debugging-secure-tunnel/

调试 webhook 时，你最想马上打开的 ngrok 功能是 Replay：它能把已经捕获的请求重新发送一遍。但它只在账号开启 Full Capture 时可用，这种模式会完整存储每个请求和响应。ngrok 自己也提醒，开启后你和团队成员可能接触到敏感数据。

对前线部署工程师（FDE）来说，这不是一个配置细节。客户的 webhook 通常带着客户的真实数据，而接收端是一台你随身携带的笔记本。

这种场景你迟早会遇到：客户系统触发了事件，你的处理程序没有反应，对方日志里只有一行含糊的报错。隧道能把请求直接送到你本机的处理程序，让你当场排查，不必每试一次就重新部署一次。前提是从一开始就设好限制。

## 真的需要隧道吗？

Stripe 文档把 ngrok 介绍为一种为 localhost 上的服务器创建临时公网 HTTPS URL 的方式，并明确说它用于测试。同一页面还给出了不需要隧道的选项：Stripe CLI 可以把事件转发到本地端口，并打印出签名密钥。

```bash
stripe listen --forward-to localhost:4242/webhook
```

所以到了客户现场，第一个问题是：webhook 服务商有没有类似的工具？没有公网 URL，就没有需要保护的公网端口。只有当发送方只能调用一个 URL 时才用 ngrok，比如客户团队完全掌控配置，你能做的只是给他们一个地址。

## 一次完整的调试过程

设想这样一个场景：客户使用 Stripe，测试账号由他们的团队自己管理，你的处理程序运行在 `localhost:4242/webhook`。你开了一条到 4242 端口的隧道，把 URL 发给客户，请他们触发一个测试事件。请求到了，但库报告签名无效。

先别怪密钥。Stripe 指出，原始请求体有任何改动都会导致校验失败。所以只要有一个中间件把 JSON 解析后再序列化回去，就足以引发这个错误，哪怕内容看起来一模一样。先确认处理程序拿到的是原封不动的原始字节，再去比对密钥。

修好之后，你设了个断点查看 payload，在那里停了 40 秒。如果发送方是 GitHub，它要求 10 秒内返回 2XX 响应，你就超时了 30 秒，这次投递会被记为失败。更好的做法是先返回 2XX，把测试 payload 写入文件，再用这个文件调试处理逻辑。

时间戳也会耗掉你的时间。一个事件在 10:00 签名，你在 10:07 重新发送。如果重发的副本保留了旧时间戳，7 分钟的间隔就超过了 Stripe 库默认的 5 分钟容差，请求会被拒绝，这正是防重放设计的本意。

这不是 bug。请客户触发一个新事件，别去追查一个并不存在的故障。

出了问题，先按症状缩小范围，再动代码。

| 症状 | 优先怀疑 | 先做什么 |
|---|---|---|
| 发送方收到 403，笔记本日志里什么都没有 | verify-webhook 在边缘拦截 | 检查 ngrok 中的密钥和时间戳设置 |
| 返回的是一个 HTML 页面，而不是处理程序的响应 | 免费套餐的插页 | 问客户能否加上绕过插页的请求头 |
| 请求到了笔记本，但签名无效 | 请求体被改动 | 在所有中间件之前记录原始请求体 |
| 第一次正常，重发时被拒 | 时间戳过期 | 创建一个新事件 |

第二行值得多说几句。在免费套餐上，ngrok 会在浏览器的 HTML 流量前插入一个插页来防范钓鱼，而 API 客户端和 webhook 可以通过一个请求头跳过它。尽早确认客户系统能否添加请求头，因为这个问题很容易被错怪到代码头上。

## 调试隧道仍然是一扇公开的门

Stripe 警告，如果不做校验，攻击者可以发送伪造事件来触发发货、授予访问权限或篡改记录。接收端是笔记本，这个风险也不会消失。如果你的处理程序连着客户的测试环境，伪造事件照样能一路传进去。

**要点:** 调试隧道仍然是一扇公开的门，要像真实端点一样把它锁好。

Stripe 建议把 IP 过滤和签名校验结合使用，GitHub 同样建议为其投递 webhook 所用的地址设置 IP 白名单。在 ngrok 一侧，`restrict-ips` 动作可以按来源 IP 放行或拦截流量。

这个动作看的是第 4 层地址，而不是 X-Forwarded-For，所以伪造请求头混不进来。代价是 IP 列表必须与实际的发送方一致。在上面的例子里，发送方是 Stripe，所以你需要的是 Stripe 投递 webhook 所用的地址；只有当客户自己的系统直接调用隧道时，才需要向客户要他们的出站 IP。

第二层是 `verify-webhook` 动作，它在 ngrok 边缘校验签名，同时检查时间戳以防重放。无效请求在到达笔记本之前就会收到 403。查阅文档，确认客户的 webhook 来源是否受支持；无论如何都要在处理程序里保留校验，因为这部分代码将来会上生产环境。

别因为“只是调试”就随手挑个密钥。GitHub 建议使用高熵随机字符串，接收端是隧道后面的笔记本时，这条建议同样适用。

还要记住，免费套餐只有一个固定的开发域名，不支持自定义域名或保留域名。这个地址在调试结束后不会变，所以用完之后要把它从客户的 webhook 配置里删掉。

## 什么时候该开 Full Capture？

Replay 能让你重复触发出错的那个请求，但它并不总是可用。如果重放的副本保留了旧时间戳，上面 10:07 的情况就会重演：超过 5 分钟，Stripe 库会拒绝它。因此这个功能在事件签名后的头几分钟里最有用。

要用它，你还得完整存储每个请求体。对于你自己生成的测试事件，这个代价几乎为零；对于含有客户真实数据的 payload，就是另一回事了。

调试开始前，先问客户测试事件里有没有真实数据，并弄清你的 ngrok 账号里有谁能看到这些数据。如果答案不明确，就别开 Full Capture，每次需要复现错误时请客户重新触发测试事件。这样稍慢一些，但更站得住脚。

## 带去客户现场之前要学什么

别从 ngrok 学起，先学 webhook 的工作原理：签名是基于什么计算的，原始请求体为什么重要，时间戳如何防止重放，处理程序为什么必须快速响应。理解了这些，任何隧道工具都只是配置问题。

从职业发展看，这项技能比你想象的更容易展示。简历上写一句“在客户环境中通过隧道调试 webhook 集成，配置 IP 过滤和签名校验，且未存储真实 payload”，就能体现你的做事方式，这是罗列工具名做不到的。

当职位描述提到集成或客户环境时，准备好完整讲一个这样的案例，说清你设了哪些限制、为什么这样设。

客户也许会忘记你用哪个工具找到了 bug，但不太会忘记他们的数据曾经待在一台笔记本上。

**本周动手试试:**

- 写一个带签名校验的小型 webhook 处理程序，然后故意把请求体解析后再序列化，看看校验失败是什么样子。
- 为客户现场的调试会话写一页检查清单：来源 IP 范围、密钥存放位置、谁能查看 payload、会话何时结束。
- 如果你在对接 Stripe，用 stripe listen --forward-to 配合你的处理程序试一试，并与经隧道的流程做对比。

## 信源

- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)

- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)

- [Verify Webhook Action](https://ngrok.com/docs/traffic-policy/actions/verify-webhook/)

- [Restrict IPs Action](https://ngrok.com/docs/traffic-policy/actions/restrict-ips/)

- [Free Plan Limits](https://ngrok.com/docs/pricing-limits/free-plan-limits)

- [Traffic Inspector HTTP Requests](https://ngrok.com/docs/obs/traffic-inspection/http-requests)
