Webhook verification
Webhook testing is one of the most common reasons to open a tunnel, and a public webhook URL accepts requests from anyone. With --verify-webhookthe edge checks the provider's HMAC-SHA256 signature on every request before forwarding it, so a forged delivery, or a stripe or slack delivery whose timestamp is outside the tolerance, is answered with 401 and never reaches your local app.
Quick start#
$ export NGSTONE_WEBHOOK_SECRET=whsec_...$ ngstone port 3000 --verify-webhook stripe --verify-webhook-path /webhooks/stripeOr keep the secret in a file readable only by you:
$ chmod 600 github.secret$ ngstone port 3000 --verify-webhook github --verify-webhook-secret-file github.secretThe secret is never accepted as a flag value, so it does not show up in ps output, and it is never printed in logs, --json events, ngstone ps, HAR exports, the edge dashboard or the admin API. Operators only see which provider a tunnel verifies.
Providers#
timestamp.body; any v1 entry may match. The t= timestamp must be within the tolerance (default 5 minutes).sha256= followed by the hex HMAC of the body.v0:timestamp:body using X-Slack-Request-Timestamp, which must be within the tolerance (default 5 minutes).sha256=. Covers Shopify and in-house senders that sign only the body.$ ngstone port 3000 --verify-webhook hmac \ --verify-webhook-header X-Shopify-Hmac-Sha256 \ --verify-webhook-encoding base64 \ --verify-webhook-secret-file shopify.secretFlags#
stripe, github, slack or hmac. HTTP tunnels only; cannot be combined with --http2 or --oidc, and ngstone serve rejects it.NGSTONE_WEBHOOK_SECRET./), ignoring case, so /webhooks/stripe.json and /index.php/webhooks/stripe are checked too. Paths the edge cannot classify (encoded slashes or backslashes, bad escapes, control bytes, backslashes, ;) are always verified. The path must not contain %, ? or #.stripe and slack, a whole number of seconds from 1s to 24h.hmac.hex or base64 for hmac.hmac, such as sha256=.Project files#
ngstone.json and ngstone.yml take a webhook block on an HTTP tunnel. Use secret_file (relative to the project file, mode 0600) or secret_env; with neither, the agent reads NGSTONE_WEBHOOK_SECRET. A tunnel with a webhook block cannot set http2: true or oidc: true, and ngstone service requires secret_file so the secret survives logout and restart.
tunnels: payments: port: 3000 subdomain: pay webhook: provider: stripe secret_file: stripe.secret path_prefix: /webhooks/stripe tolerance: 5m bot: port: 3001 webhook: provider: slack secret_env: SLACK_SIGNING_SECRET{ "tunnels": { "hooks": { "target": "3000", "webhook": {"provider": "github", "secret_env": "GITHUB_WEBHOOK_SECRET", "path_prefix": "/github"} } }}What gets rejected#
A missing or malformed signature header is rejected before any of the body is read. Otherwise the edge buffers the body (up to the smaller of its -webhook-max-body-bytes and -max-body-bytes limits, 1 MiB by default), checks the signature with a constant-time comparison, then forwards the untouched body. All verifications together share a -webhook-buffer-bytes budget (64 MiB by default). Failures get a short plain-text reason:
401 webhook signature rejected: missing signature401 webhook signature rejected: malformed signature401 webhook signature rejected: invalid signature401 webhook signature rejected: timestamp outside tolerance413 request entity too large503 webhook verification is busySignature rejections are counted in ngstoned_rejected_webhook_signature_total; a 503 (sent with Retry-After) means the buffer budget is spent and is counted in ngstoned_rejected_webhook_buffer_total.
Security notes#
The edge holds the secret
--insecure the control channel is plaintext, so the agent refuses to send the secret unless the edge address is loopback (localhost, 127.0.0.0/8 or ::1).Replay protection is limited
stripe and slack reject a delivery only when its signed timestamp is outside the tolerance. The edge keeps no nonce cache, so a captured delivery can be replayed within that window. github and hmacsign no timestamp and have no replay protection at all. Deduplicate on the provider's event ID in your app.If you set a webhook path, requests whose path does not contain it at a segment boundary are forwarded without a check. Leave it empty to verify everything the tunnel receives. With --multi-connector, every connector must present the same webhook settings and secret. An edge too old to verify webhooks makes the agent refuse to bind instead of opening an unprotected tunnel.