FDE Times 数据在招 FDE 职位 882▼2 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 52在招公司 185支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

工具

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

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

分享微博

要点速览

  • ngrok 能把客户的 webhook 送到你笔记本上的处理程序,但 Stripe 明确说这种做法只用于测试。
  • 未做认证的公网 URL 可能收到伪造事件,因此要把 IP 过滤和签名校验结合起来。
  • Traffic Inspector 的 Replay 需要开启 Full Capture,它会完整存储每个请求和响应,涉及真实数据时要三思。
一棵两步决策树。如果 webhook 服务商有 CLI(如 Stripe),就不需要隧道。如果没有,先用 IP 过滤和签名校验锁住隧道,再问:能否确定测试事件不含真实数据?能确定就开启 Full Capture;不能确定就不开,并请客户重新发送事件。
只有确定测试事件不含真实客户数据时,才值得开启 Full Capture;拿不准时,每次需要复现 bug 都请客户重新发送事件。

调试 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,但不太会忘记他们的数据曾经待在一台笔记本上。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 5: 部署上线E2B 沙箱默认能连外网,得自己动手关掉关闭 allowInternetAccess 即可封锁所有出站路由,一段短脚本就能向客户安全团队证明这一点。