Postman Ubuntu版如何使用Webhooks

在 Ubuntu 版 Postman 中使用 Webhooks 的两种场景

• 场景一：用 Postman 作为“发送方”，向外部服务的 Webhook 地址推送数据（例如触发 GitHub、n8n、企业微信/飞书机器人等）。
• 场景二：用 Postman 的“集合 Webhooks”功能，让外部事件通过 Postman API 触发你的集合运行，并在集合脚本中读取事件数据。

场景一 发送 Webhook 请求

• 新建请求：在 Postman 中新建一个请求，方法通常为 POST，URL 填入目标服务的 Webhook 地址。
• 设置请求头：按对方要求设置 Content-Type: application/json 等必要头部。
• 设置请求体：在 Body 选择 raw → JSON，填入要发送的数据，例如： { “event”: “push”, “repository”: “my-repo”, “ref”: “refs/heads/main” }
• 发送并校验：点击 Send，观察返回状态码（如 200/201）与响应体，确认对方已成功接收。
• 本地调试技巧：若目标服务在你本机（如 http://localhost:3000/webhook），在 Ubuntu 上可用 ngrok 暴露公网地址：
  • 启动本地服务（例如监听 3000 端口）
  • 终端运行：ngrok http 3000
  • 复制输出的 https 公网地址（如：https://xxxx.ngrok-free.app），将其作为 Webhook URL 填入 Postman 或外部系统
• 常见要点：
  • 很多 Webhook 要求请求体为 JSON，并在响应中尽快返回 2xx，否则可能判定为失败或重试
  • 需要签名校验的服务（如 GitHub）要在请求头中加入 X-Hub-Signature-256 等签名头，值由你的 Secret 计算生成

场景二 用集合 Webhooks 触发 Postman 集合运行

• 能力说明：集合 Webhooks 允许外部系统在特定事件发生时，向 Postman 发送 POST 请求以触发某个集合运行；请求体必须是 JSON，其数据可在集合运行期间通过 globals.previousRequest 读取与解析。
• 创建步骤：
  • 在 Postman 中准备好要被触发的集合，并记下集合的 UID（在集合概览页面可看到）
  • 使用 Postman API 创建 Webhook（集合 Webhooks 只能通过 Postman API 创建），示例请求： curl -X POST https://api.getpostman.com/webhooks
    -H “X-Api-Key: <你的Postman-API-Key>”
    -H “Content-Type: application/json”
    -d ‘{ “name”: “trigger-my-collection”, “collection_uid”: “<你的集合UID>”, “webhook_url”: “https://<你的公网地址>/webhook”, “events”: [“collection.run”], “active”: true }’
  • 在你的服务器或 n8n、Zapier 等工具中配置一个 HTTP 请求节点，向上述 Webhook URL 发送 POST，Body 为 JSON，例如： { “event”: “order.paid”, “order_id”: “20251124001”, “amount”: 99.00 }
  • 在集合的预请求脚本或测试脚本中读取数据： var payload = JSON.parse(globals.previousRequest || ‘{}’).data; pm.environment.set(“event”, payload.event); pm.environment.set(“order_id”, payload.order_id);
  • 运行与验证：当外部系统 POST 到 Webhook URL 时，Postman 会触发集合运行，脚本中的变量将被设置，可在后续请求中使用

常见问题与排查

• 本机无法被外网访问：使用 ngrok 或类似隧道工具将 localhost 暴露为公网地址，再将该地址配置到外部系统或 Postman Webhook 的回调 URL 中。
• 403/401 或无响应：检查 Postman API Key、目标服务是否要求 签名/Token、以及请求头是否正确（如 Content-Type: application/json）。
• 事件数据拿不到：确认 Webhook 请求体为 JSON，并在集合脚本中使用 globals.previousRequest 正确解析；注意仅在集合运行上下文中可用。
• 触发失败或重复：确保 Webhook 服务在收到请求后尽快返回 2xx；部分平台会按策略重试未确认的事件。

快速对照