receive-webhooks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Receive webhooks

接收 webhook

Receive an inbound webhook, verify the provider's signature at ngrok's edge, and deliver it to the user's service - without writing verification code and, when wanted, without exposing the service publicly.
在 ngrok 边缘接收传入的 webhook、验证服务商的签名,并将其转发到用户的服务——无需编写验证代码,并且可选择不让服务暴露在公共互联网上。

Before you start

准备工作

Auth is required (
ngrok-setup
). This job uses a Traffic Policy - pull the
verify-webhook
and
forward-internal
mechanics, and the endpoint choice, from
ngrok-engine
.
需要完成身份验证(
ngrok-setup
)。此任务使用 Traffic Policy——从
ngrok-engine
中引入
verify-webhook
和
forward-internal
机制以及端点选择方式。

Core pattern (every case)

核心模式(所有场景)

Two actions in sequence:
  1. verify-webhook
    - validate the signature (fails closed with 403 unless
    enforce: false
    ).
  2. deliver - to a local port for testing, or
    forward-internal
    to a private receiver for production.
yaml
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 }
Provider list, per-provider secret setup, replay protection, and endpoint-verification challenges:
references/providers.md
.
按顺序执行两个操作:
  1. verify-webhook
    ——验证签名(除非设置
    enforce: false
    ,否则验证失败时默认拒绝访问并返回 403)。
  2. 转发——测试时转发到本地端口,生产环境中则通过
    forward-internal
    转发到私有接收服务。
yaml
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 }
服务商列表、各服务商的 secret 配置、重放防护以及端点验证挑战:
references/providers.md
。

Choose the shape

选择形态

  • Testing / debugging locally -> agent endpoint forwarding to a local port. Fastest. Verify, then deliver to the port instead of
    forward-internal
    .
  • Production / private / regulated / shared gateway -> cloud endpoint (public, always-on) running the verify+route policy, forwarding to an internal endpoint that holds the receiver off the public internet. See
    ngrok-engine
    for why cloud+internal here.
  • 在本地测试/调试 -> 通过 agent endpoint 转发到本地端口。速度最快。先验证,再将请求转发到该端口,而不是使用
    forward-internal
    。
  • 生产环境/私有/受监管/共享 gateway -> 使用 cloud endpoint(公共、始终在线)运行验证和路由 policy,再转发到 internal endpoint,使接收服务不暴露在公共互联网上。有关此场景为何采用 cloud+internal 方案,请参阅
    ngrok-engine
    。

Apply it

应用方式

Attach the policy and bring up the endpoint(s) on the user's surface - see
ngrok-surfaces
. The policy body is identical on every surface; only attachment differs.
Give the user the public URL to paste into the provider's webhook settings.
在用户的 surface 上附加 policy 并启动端点——参见
ngrok-surfaces
。每个 surface 上的 policy 内容完全相同,区别仅在于附加方式。
向用户提供公共 URL,供其粘贴到服务商的 webhook 设置中。

Worked scenarios (same mechanism, different emphasis)

实际场景(机制相同,侧重不同)

  • "Keep our receiver off the public internet." Cloud endpoint verifies at the edge;
    forward-internal
    to an internal-bound receiver. No inbound firewall ports; the agent connects outbound on 443.
  • "Regulated / compliant delivery." Same, plus: secrets in a Vault (not plaintext), signatures verified before anything touches your systems, and you can add IP allowlists or JWT checks in the same policy. Verification fails closed.
  • "One gateway for all providers." Multiple path-routed rules in one policy (
    /stripe
    ,
    /github
    , ..), each verifying its provider then forwarding to the right internal service - verification, routing, and secrets in one place instead of per-service code.
  • “让我们的接收服务保持不暴露在公共互联网上。” Cloud endpoint 在边缘完成验证,再通过
    forward-internal
    转发到仅限内部访问的接收服务。无需开放入站防火墙端口;agent 通过 443 发起出站连接。
  • “受监管/合规转发。” 采用相同机制,并增加以下措施:secret 存储在 Vault 中(而非明文形式);在任何请求接触系统之前完成签名验证;还可以在同一个 policy 中添加 IP allowlist 或 JWT 检查。验证失败时默认拒绝访问。
  • “所有服务商共用一个 gateway。” 在一个 policy 中配置多条基于路径的路由规则(
    /stripe
    、
    /github
    等),每条规则先验证对应服务商的签名,再转发到正确的内部服务——将验证、路由和 secret 集中管理,无需在各服务中分别编写代码。

Verify it works

验证是否正常工作

  • Trigger a test event from the provider dashboard, or
    curl
    with a valid signature header.
  • Valid -> reaches the upstream; invalid -> 403 at the edge.
  • Inspect exact headers/body of each inbound request in the agent's web inspector (default http://localhost:4040) or the dashboard Traffic Inspector.
  • 从服务商 dashboard 触发测试事件,或使用带有有效签名 header 的
    curl
    请求。
  • 验证有效 -> 请求到达上游服务;验证无效 -> 边缘返回 403。
  • 在 agent 的 web inspector(默认 http://localhost:4040)或 dashboard 的 Traffic Inspector 中检查每个传入请求的确切 headers/body。

Notes for agents

Agent 注意事项

  • Don't tell the user to write signature-verification code - the whole point is that
    verify-webhook
    replaces it.
  • Never hardcode the signing secret; use a Vault or env var.
  • Do not ask the user to paste the signing secret into the chat, and do not accept one offered that way. Have them put it in a Vault themselves, or in an env var, and reference it from the policy. When
    ngrok-surfaces
    ("Account resources") picks the ngrok MCP server, create the vault with
    gw_create_vault
    and the secret with
    gw_create_secret
    . The secret tool gives the user a dashboard form for the value, so no API key is needed. Otherwise use the dashboard or
    ngrok api secrets create
    . A
    whsec_...
    in a transcript is a leaked secret.
  • Nothing that rewrites the body may run before
    verify-webhook
    , or the signature check breaks.
  • If the ngrok MCP server is connected,
    gw_query_traffic_inspector
    shows whether the provider's request arrived and what the endpoint returned. Check it before you debug the receiver.
  • 不要让用户编写签名验证代码——
    verify-webhook
    的核心作用正是取代这类代码。
  • 切勿硬编码 signing secret;应使用 Vault 或 env var。
  • 不要要求用户将 signing secret 粘贴到聊天中,也不要接受用户以此方式提供的 secret。应让用户自行将其存入 Vault 或 env var,并在 policy 中引用。当
    ngrok-surfaces
    ("Account resources")选择 ngrok MCP server 时,使用
    gw_create_vault
    创建 vault,并使用
    gw_create_secret
    创建 secret。Secret 工具会为用户提供用于输入值的 dashboard 表单,因此无需 API key。否则,使用 dashboard 或
    ngrok api secrets create
    。记录中出现
    whsec_...
    即表示 secret 已泄露。
  • 在
    verify-webhook
    之前不得运行任何会重写 body 的操作,否则签名检查将失效。
  • 如果已连接 ngrok MCP server,可以使用
    gw_query_traffic_inspector
    查看服务商的请求是否到达以及端点返回了什么。在调试接收服务之前应先检查它。