Receive webhooks
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.
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.
Core pattern (every case)
Two actions in sequence:
verify-webhook - validate the signature (fails closed with 403 unless enforce: false).
- deliver - to a local port for testing, or
forward-internal to a private receiver for production.
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.
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.
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.
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.
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.
Notes for agents
- 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 via ngrok dashboard or API (
ngrok api secrets create) or an env var themselves, and reference it from the policy. A whsec_... in a transcript is a leaked secret.
- Nothing that rewrites the body may run before
verify-webhook, or the signature check breaks.
1---2name: receive-webhooks3description: Receive and verify inbound webhooks from providers like Stripe, GitHub, Twilio, Slack, or Shopify and deliver them to a local or private service without exposing that service to the public internet. Verify signatures at the edge with no app code; route third-party callbacks to a service behind a firewall, including regulated (HIPAA/PCI) environments or a centralized webhook gateway shared across teams. Use when the user needs to receive, test, or debug webhooks locally, wants signature verification without writing it, or must route callbacks to a private service.4license: MIT5metadata:6 source: https://skillmd.com/skills/ngrok/receive-webhooks7 author: ngrok8 version: "1.0"9 category: connectivity10 surface: job11compatibility: Requires ngrok CLI installed and authenticated. Requires an ngrok API key to create Vaults and Secrets from the command line.12---1314# Receive webhooks1516Receive 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.1718## Before you start1920Auth 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`.2122## Core pattern (every case)2324Two actions in sequence:25261. `verify-webhook` - validate the signature (fails closed with 403 unless `enforce: false`).272. deliver - to a local port for testing, or `forward-internal` to a private receiver for production.2829```yaml30on_http_request:31 - actions:32 - type: verify-webhook33 config:34 provider: stripe35 secret: "${secrets.get('webhooks', 'stripe-signing-secret')}"36 - type: forward-internal37 config: { url: https://billing.internal }38```3940Provider list, per-provider secret setup, replay protection, and endpoint-verification challenges: `references/providers.md`.4142## Choose the shape4344- **Testing / debugging locally** -> agent endpoint forwarding to a local port. Fastest. Verify, then deliver to the port instead of `forward-internal`.45- **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.4647## Apply it4849Attach 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.5051Give the user the public URL to paste into the provider's webhook settings.5253## Worked scenarios (same mechanism, different emphasis)5455- **"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.56- **"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.57- **"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.5859## Verify it works6061- Trigger a test event from the provider dashboard, or `curl` with a valid signature header.62- Valid -> reaches the upstream; invalid -> 403 at the edge.63- Inspect exact headers/body of each inbound request in the agent's web inspector (default http://localhost:4040) or the dashboard Traffic Inspector.6465## Notes for agents6667- Don't tell the user to write signature-verification code - the whole point is that `verify-webhook` replaces it.68- Never hardcode the signing secret; use a Vault or env var.69- 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 via ngrok dashboard or API (`ngrok api secrets create`) or an env var themselves, and reference it from the policy. A `whsec_...` in a transcript is a leaked secret.70- Nothing that rewrites the body may run before `verify-webhook`, or the signature check breaks.