receive-webhooks

接收 Webhook

接收传入的 Webhook，在 ngrok 边缘验证提供方的签名，并将其传送到用户的服务——无需编写验证代码；如有需要，也无需将服务公开。

开始之前

需要身份验证（ngrok-setup）。此任务使用 Traffic Policy——从 ngrok-engine 获取 verify-webhook 和 forward-internal 的使用方式，以及端点的选择方法。

核心模式（适用于所有情况）

按顺序执行两个操作：

1. verify-webhook - 验证签名（除非设置 enforce: false，否则验证失败时会以 403 拒绝）。
2. 传送 - 测试时传送到本地端口；生产环境中则使用 forward-internal 转发到私有接收端。

on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: stripe
          secret: "${secrets.get('webhooks', 'stripe-signing-secret')}"
      - type: forward-internal
        config: { url: https://billing.internal }

提供方列表、各提供方的密钥设置、重放保护和端点验证质询：references/providers.md。

选择方案

• 本地测试 / 调试 -> Agent 端点转发到本地端口。速度最快。先验证，再传送到该端口，而不是使用 forward-internal。
• 生产环境 / 私有环境 / 受监管环境 / 共享网关 -> 云端点（公开、始终在线），运行验证和路由策略，并转发到内部端点，使接收端不暴露于公共互联网。请参阅 ngrok-engine，了解此处使用云端点和内部端点的原因。

应用

在用户使用的界面上附加策略并启动端点——请参阅 ngrok-surfaces。所有界面的策略正文都相同；只有附加方式不同。

将公开 URL 提供给用户，让他们粘贴到提供方的 Webhook 设置中。

场景示例（机制相同，侧重点不同）

• “让我们的接收端不暴露于公共互联网。” 云端点在边缘验证；使用 forward-internal 转发到绑定内部网络的接收端。无需开放入站防火墙端口；Agent 通过 443 端口发起出站连接。
• “受监管 / 合规的传送。” 同上，另外：将密钥存储在 Vault 中（而非明文存储），在请求触及系统之前验证签名，并且可以在同一策略中添加 IP 允许列表或 JWT 检查。验证失败时会拒绝请求。
• “为所有提供方使用同一个网关。” 在一个策略中设置多条按路径路由的规则（/stripe、/github、..），分别验证各提供方，再转发到相应的内部服务——将验证、路由和密钥集中管理，而不是为每个服务编写代码。

验证是否有效

• 在提供方控制面板中触发测试事件，或使用带有效签名标头的 curl。
• 有效请求 -> 到达上游；无效请求 -> 在边缘返回 403。
• 在 Agent 的 Web 检查器（默认地址 http://localhost:4040）或控制面板的 Traffic Inspector 中，检查每个入站请求的确切标头和正文。

给 Agent 的说明

• 不要让用户编写签名验证代码——verify-webhook 的作用就是取代这部分代码。
• 切勿将签名密钥硬编码；应使用 Vault 或环境变量。
• 不要要求用户将签名密钥粘贴到聊天中，也不要接受他们以这种方式提供的密钥。让用户自行将其存入 Vault，或设置为环境变量，并在策略中引用它。当 ngrok-surfaces（“Account resources”）选择 ngrok MCP 服务时，使用 gw_create_vault 创建 Vault，并使用 gw_create_secret 创建密钥。密钥工具会向用户提供一个控制面板表单以填写密钥值，因此无需 API key。否则，请使用控制面板或 ngrok api secrets create。记录中出现的 whsec_... 表示密钥已泄露。
• 在 verify-webhook 之前，不得运行任何会改写正文的操作，否则签名检查会失败。
• 如果已连接 ngrok MCP 服务，gw_query_traffic_inspector 可显示提供方的请求是否已到达，以及端点返回了什么。在调试接收端之前先检查这里。