Quickmock

测试 Webhook 接收器

捕获传入的 Webhook 调用并实时检查其请求头和正文。

要测试 Webhook 接收器，您需要一个发送者实际可以访问的公开 URL，这就排除了本地主机。一个模拟的 Webhook 端点会立即为您提供该 URL：它接受 POST，返回提供商期望的确认响应，并记录完整的请求，以便您可以读取发送者实际传输的请求头和正文 — 而不是文档里声称的那些。

为什么提供商不能只调用本地主机？

Webhook 是提供商的服务器在调用您的服务器。http://localhost:3000 在提供商看来也是指“这台机器”，所以他们的调用永远不会离开他们的网络。隧道工具通过暴露您的笔记本电脑来解决这个问题；模拟端点则通过将您的笔记本电脑完全从循环中移除来解决这个问题。

这种差异在早期很重要。在您的处理程序存在之前，您实际需要知道的是提供商发送了什么 — 哪些请求头，哪些正文，哪种内容类型。模拟在一次发送中就回答了这个问题，您可以针对记录的请求而不是文档的示例来编写处理程序。

端点应该向发送者回复什么？

几乎每个服务提供商都将任何 2xx 视为成功，将所有其他状态视为值得重试的失败，因此请快速返回 200 并保持响应体较小。Stripe 会在非 2xx 时重试数天；GitHub 会将失败记录在交付日志中。它们都对缓慢的处理程序进行与损坏处理程序一样严厉的惩罚。

某些服务提供商想要的不仅是一个状态码。Slack 的 Events API 只有在端点回显验证请求中的 challenge 值之后才会启用该端点。如果你的端点必须使用从请求中派生的内容进行响应，请模拟该回显而不是固定的主体。

你如何看到发送者实际发送的内容？

打开模拟的检查器，每次交付都会列出其方法、标头、正文和时间戳。这部分很难通过任何其他方式获得：签名标头、确切的内容类型，以及服务提供商文档记录与实际传输内容之间的差异。

从服务提供商的仪表板触发真实的事件，而不是发送自己手写的 POST 请求。你自己编写的负载只会证实你的假设；服务提供商发送的负载可以纠正它们。

相同事件的两次交付值得并排比较。服务提供商在失败后会重新交付，并且重试并不总是与第一次尝试逐字节相同 —— 如果服务提供商发送交付 ID 标头，这就是你的幂等键应该构建的来源，而不是正文的哈希值。

通常会出什么问题？

  • 使用你发明的负载进行测试。 这证明你的解析器可以处理你自己的 JSON，这毫无疑问。
  • 在工作完成之前 —— 或之后返回 200。 快速确认，然后异步处理。服务提供商的超时时间远短于缓慢处理程序完成的时间。
  • 忽略重新交付。 重试意味着同一个事件到达两次。处理程序必须是幂等的，发送两次相同的交付是证明这一点的方法。
  • 假设模拟器会验证签名。 它不会。签名检查是你的处理程序的工作，必须针对实际发送者进行测试。

何时使用此功能

集成第三方 Webhook（Stripe、GitHub、支付提供商）意味着您需要一个 URL 来指向它 — 并且需要一种方法来准确查看它发送了什么。创建一个 POST 模拟，将其 URL 提供给提供商，然后在实时请求检查器中观察每一次调用：方法、请求头、查询参数、正文。

创建模拟

curl -X POST https://quickmock.dev/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "POST",
  "response_status": 200,
  "response_body": "{\"received\":true}"
}'

调用它

curl -X POST -H 'Content-Type: application/json' -d '{"event":"payment.succeeded"}' https://quickmock.dev/m/<slug>

打开模拟页面并粘贴其管理令牌，即可在私有实时检查器中查看传入的方法、请求头、查询参数和正文。

您将获得什么

{"received":true}

常见问题解答

我可以在不暴露本地机器的情况下测试 Webhook 吗？
是的 —— 这就是模拟接收器的重点。服务提供商调用一个不是你的笔记本电脑的公共 URL，因此你无需隧道也无需打开端口即可捕获和读取交付。
我会看到服务提供商发送的签名标头吗？
是的。检查器记录每次交付的标头，包括服务提供商的签名标头，如 Stripe-Signature 和 X-Hub-Signature-256。Authorization、Cookie 和 X-Api-Key 等凭据标头会被脱敏存储，对于重复的标头只保留第一个值。验证签名仍然是你的处理程序的工作 —— 模拟器接受到达的任何内容。
端点可以使用从请求中获取的值进行回复吗？
是的。请求标记（token）允许响应回显传入请求体的一部分，这是像 Slack 的 url_verification 这样的握手在启用端点之前所要求的。

构建您自己的模拟

创建模拟

适用于此场景的现成模板： 模拟 Stripe webhook 负载, 模拟 Shopify 订单 Webhook, 模拟 GitHub 推送 Webhook

相关指南

← 所有指南

最后更新: 2026-10-17