receive-webhooks
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.
ngrok · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ngrok/skills --skill receive-webhooksAbout this skill
name: receive-webhooks description: 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. license: MIT metadata: author: ngrok version: "1.0" category: connectivity surface: job compatibility: Requires ngrok CLI installed and authenticated. Requires the ngrok MCP server or an ngrok API key to create Vaults and Secrets.
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 unlessenforce: false).- deliver - to a local port for testing, or
forward-internalto 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-enginefor 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-internalto 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
curlwith 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-webhookreplaces 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 withgw_create_vaultand the secret withgw_create_secret. The secret tool gives the user a dashboard form for the value, so no API key is needed. Otherwise use the dashboard orngrok api secrets create. Awhsec_...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_inspectorshows whether the provider's request arrived and what the endpoint returned. Check it before you debug the receiver.