无需管道工程，调试 Webhook
最后更新:
每一个 Webhook 集成都始于同一个不起眼的问题：服务商的服务器需要调用你的代码，而你的代码运行在你的笔记本电脑上，外界无法访问你的笔记本电脑。所以在你调试真正的工作——签名校验、负载形状、处理器逻辑——之前，你得先搭建管道工程：一条隧道、一次预发布部署、一个转发到你机器的公共 URL。本文讲的是如何用临时接收器跳过这一步，比如本站的 Webhook 测试器：创建一个地址，把服务商指向它，触发事件，然后读取确切到达的内容。然后按照真相而不是文档来编写你的处理器。
调试循环，以及它在哪里断裂
健康的 Webhook 循环很短：服务商中发生一个事件，服务商把签名的负载 POST 到你的端点，你的端点验证签名、解析请求体、完成工作并回复 200。不健康的循环——人人都熟悉的那种——在每一步周围都加了一层迷雾。服务商的仪表板说投递失败了，返回 500，或 404，或什么都没说。那是你的代码在应答、中间的代理，还是端点 URL 打错了字？重试带着同一个事件 id 到达——还是说它是同一笔支付的一个新事件？文档展示了一个整洁的 JSON 示例，但生产负载带有额外的字段、示例压平的嵌套对象，偶尔还有示例从未提及的内容类型。Stripe 和 GitHub 的 Webhook 文档（链接在下方）都强调同样的纪律——验证签名、快速应答、处理重复——而在你能看到一次真实投递之前，这些都无从练起。
断裂几乎从来不在有趣的逻辑里。它在你以为发送了什么与实际发送了什么之间的鸿沟里：在你的框架已经解析并重新序列化的请求体上计算出的签名头、从错误的仪表板复制的密钥、你的 switch 语句拼写略有不同的事件类型、一个对仪表板里的测试事件有效却对生产环境的真实事件无效的处理器。所有这些从你自己的日志内部都看不见，因为你的日志始于你的代码已经做出第一个错误假设之后。由不是你的代码的东西记录的一次被捕获的投递，是能让循环缩短的事实真相。
临时接收器能为你买到什么
临时接收器是一个公共 URL，它的全部工作就是接受一切并展示给你：本站的 Webhook 测试器 一键创建它，保留 30 分钟，记录最多 50 次投递及其方法、路径与查询参数、请求头和请求体（每个最多 256 KB），然后自动删除一切。它买到的是顺序。你不必为了观察流量就把写了一半的处理器部署到公共机器上——然后同时调试部署和处理器——而是把观察与实现分开。先看几个真实事件到达，学习它们实际的形状。然后在本地对照被捕获的负载编写处理器，你可以手动把它们重放到自己的测试中。最后把服务商指向真实端点，再触发一次事件，此时你已经确切知道一次正确的投递长什么样，以及你的处理器应该对它做什么。
当对话跨越团队边界时，它还能买到证据。“你的 Webhook 把金额发成了字符串”是一场争论；一条显示 "amount": "2000" 的被捕获投递是一个事实。同一条捕获能回答服务商支持工单会问的问题——哪个事件 id、哪个时间戳、哪个签名头在场——而无需一轮日志考古，它也能判定一次缺失的投递到底是根本没发送，还是发送到了某个被遗忘的旧测试地址。同样的哲学，相邻的工具：当问题是重定向而非负载时，HTTP 状态链追踪器 从服务器的视角展示一个 URL 的行为。
工作流程：配合本工具
一：打开 Webhook 测试器 并创建一个钩子。复制接收 URL——从这一刻起把这个 URL 当作凭证，原因见下一节。二：把它粘贴到服务商的 Webhook 设置中作为测试端点——Stripe、GitHub 和大多数服务商都允许几个端点，所以你的生产端点不受影响——或者如果你调试的是自己控制的发送方，就粘贴到你自己的服务配置里。三：以诚实的方式触发事件。使用服务商的真实流程（测试模式支付、向草稿分支的真实推送），而不仅仅是仪表板的“发送测试事件”按钮，因为测试事件有时恰恰在你在乎的字段上与真实事件不同。四：读取捕获。先检查方法和内容类型，再检查签名和事件头，然后在信任任何美化打印视图之前先看原始文本的请求体。
五：对照这条捕获编写或修复你的处理器。对照原样收到的原始请求体验证签名——这正是捕获展示未解析字节的原因——并让你的处理器对你现在能看到在重试间稳定的事件 id 做到幂等。六：删除钩子（或让它的 30 分钟到期），从服务商那里移除测试端点，把投递重新指向你的真实处理器。七：再触发一次事件，看着你自己的端点应答它。如果现在它失败了，被捕获的良好投递与你的处理器的行为之间的差异就是全部的 bug，而这个差异是可以检查而不是猜测的。
安全：URL 就是凭证
一个任何人都能读的接收器不需要登录，这种便利有你应该留意的代价：URL 中的钩子 id 是唯一的凭证，它同时授权发送和查看。任何获得 URL 的人——从截图、聊天记录、共享屏幕——都能读取钩子存活期间捕获的每一个负载。所以规则就是密码规则：不要公开张贴 URL，不要把它用于实时生产馈送，会话结束时删除钩子，而不是让捕获内容坐满那半小时。负载从另一面也值得同样的尊重：一次真实的支付或推送负载可能包含客户电子邮件地址、订单详情和你不会粘贴到公开 gist 里的元数据，而一条被捕获的投递正是这种文档。测试模式、草稿仓库和合成事件的存在，正是为了让调试产物里没有任何值得窃取的东西。
测试器自身的限制是安全故事的一部分，并已在工具页上明确说明：捕获内容只在检查服务器上保存到钩子过期或你删除它为止——最长 30 分钟——请求体上限为 256 KB，钩子上限为 50 个请求，接收器从不抓取、跟随或重放任何内容，因此被捕获的负载无法变成服务器的出站流量。判断仍然留给你。如果一个负载落到陌生人手里会成为问题，它根本不属于共享查看器：那次调试会话请用你自己的基础设施，就像对待生产密钥一样。便利工具的位置，是在构成大多数调试日常的低敏感度工作上挣来的。
局限：只接收，只检查
本工具刻意不做的是检查之后的一切。它不把投递转发到你的笔记本电脑（那是隧道的工作，而当处理器已经存在、你要在实时迭代时，隧道正是合适的工具），它不把被捕获的请求重放到你的真实端点，它不转换或签名任何内容，它也不保留超过 30 分钟的历史。这些缺失正是设计本身：会转发的接收器是一个让你的流量流经它的代理，会重放的接收器是一个发送方，两者都是比一个 30 分钟收件匣更大的信任。把测试器用在它适合的阶段——在构建处理器之前和构建过程中看清真相——而一旦集成上线，就让位于你自己的端点，在你自己的认证和日志之后接管。