想在 ngrok 重放 webhook,就得完整存下客户数据
Stripe CLI 无需公网 URL 就能转发事件;非开隧道不可时,要在第一个请求到来前设好限制。
要点速览
- ngrok 能把客户的 webhook 送到你笔记本上的处理程序,但 Stripe 明确说这种做法只用于测试。
- 未做认证的公网 URL 可能收到伪造事件,因此要把 IP 过滤和签名校验结合起来。
- Traffic Inspector 的 Replay 需要开启 Full Capture,它会完整存储每个请求和响应,涉及真实数据时要三思。
调试 webhook 时,你最想马上打开的 ngrok 功能是 Replay:它能把已经捕获的请求重新发送一遍。但它只在账号开启 Full Capture 时可用,这种模式会完整存储每个请求和响应。ngrok 自己也提醒,开启后你和团队成员可能接触到敏感数据。
对前线部署工程师(FDE)来说,这不是一个配置细节。客户的 webhook 通常带着客户的真实数据,而接收端是一台你随身携带的笔记本。
这种场景你迟早会遇到:客户系统触发了事件,你的处理程序没有反应,对方日志里只有一行含糊的报错。隧道能把请求直接送到你本机的处理程序,让你当场排查,不必每试一次就重新部署一次。前提是从一开始就设好限制。
真的需要隧道吗?
Stripe 文档把 ngrok 介绍为一种为 localhost 上的服务器创建临时公网 HTTPS URL 的方式,并明确说它用于测试。同一页面还给出了不需要隧道的选项:Stripe CLI 可以把事件转发到本地端口,并打印出签名密钥。
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,但不太会忘记他们的数据曾经待在一台笔记本上。
这篇文章对你有帮助吗?
感谢你的反馈!