receive-webhooks
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReceive 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 (). This job uses a Traffic Policy - pull the and mechanics, and the endpoint choice, from .
ngrok-setupverify-webhookforward-internalngrok-engine需要完成身份验证()。此任务使用 Traffic Policy——从 中引入 和 机制以及端点选择方式。
ngrok-setupngrok-engineverify-webhookforward-internalCore pattern (every case)
核心模式(所有场景)
Two actions in sequence:
- - validate the signature (fails closed with 403 unless
verify-webhook).enforce: false - deliver - to a local port for testing, or to a private receiver for production.
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 }Provider list, per-provider secret setup, replay protection, and endpoint-verification challenges: .
references/providers.md按顺序执行两个操作:
- ——验证签名(除非设置
verify-webhook,否则验证失败时默认拒绝访问并返回 403)。enforce: false - 转发——测试时转发到本地端口,生产环境中则通过 转发到私有接收服务。
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.mdChoose 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 for why cloud+internal here.
ngrok-engine
- 在本地测试/调试 -> 通过 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 . The policy body is identical on every surface; only attachment differs.
ngrok-surfacesGive the user the public URL to paste into the provider's webhook settings.
在用户的 surface 上附加 policy 并启动端点——参见 。每个 surface 上的 policy 内容完全相同,区别仅在于附加方式。
ngrok-surfaces向用户提供公共 URL,供其粘贴到服务商的 webhook 设置中。
Worked scenarios (same mechanism, different emphasis)
实际场景(机制相同,侧重不同)
- "Keep our receiver off the public internet." Cloud endpoint verifies at the edge; to an internal-bound receiver. No inbound firewall ports; the agent connects outbound on 443.
forward-internal - "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, ..), each verifying its provider then forwarding to the right internal service - verification, routing, and secrets in one place instead of per-service code./github
- “让我们的接收服务保持不暴露在公共互联网上。” Cloud endpoint 在边缘完成验证,再通过 转发到仅限内部访问的接收服务。无需开放入站防火墙端口;agent 通过 443 发起出站连接。
forward-internal - “受监管/合规转发。” 采用相同机制,并增加以下措施:secret 存储在 Vault 中(而非明文形式);在任何请求接触系统之前完成签名验证;还可以在同一个 policy 中添加 IP allowlist 或 JWT 检查。验证失败时默认拒绝访问。
- “所有服务商共用一个 gateway。” 在一个 policy 中配置多条基于路径的路由规则(、
/stripe等),每条规则先验证对应服务商的签名,再转发到正确的内部服务——将验证、路由和 secret 集中管理,无需在各服务中分别编写代码。/github
Verify it works
验证是否正常工作
- Trigger a test event from the provider dashboard, or with a valid signature header.
curl - 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 replaces it.
verify-webhook - 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 ("Account resources") picks the ngrok MCP server, create the vault with
ngrok-surfacesand the secret withgw_create_vault. The secret tool gives the user a dashboard form for the value, so no API key is needed. Otherwise use the dashboard orgw_create_secret. Angrok api secrets createin a transcript is a leaked secret.whsec_... - Nothing that rewrites the body may run before , or the signature check breaks.
verify-webhook - If the ngrok MCP server is connected, shows whether the provider's request arrived and what the endpoint returned. Check it before you debug the receiver.
gw_query_traffic_inspector
- 不要让用户编写签名验证代码——的核心作用正是取代这类代码。
verify-webhook - 切勿硬编码 signing secret;应使用 Vault 或 env var。
- 不要要求用户将 signing secret 粘贴到聊天中,也不要接受用户以此方式提供的 secret。应让用户自行将其存入 Vault 或 env var,并在 policy 中引用。当 ("Account resources")选择 ngrok MCP server 时,使用
ngrok-surfaces创建 vault,并使用gw_create_vault创建 secret。Secret 工具会为用户提供用于输入值的 dashboard 表单,因此无需 API key。否则,使用 dashboard 或gw_create_secret。记录中出现ngrok api secrets create即表示 secret 已泄露。whsec_... - 在 之前不得运行任何会重写 body 的操作,否则签名检查将失效。
verify-webhook - 如果已连接 ngrok MCP server,可以使用 查看服务商的请求是否到达以及端点返回了什么。在调试接收服务之前应先检查它。
gw_query_traffic_inspector