DocsGuidesWebhook verification

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/stripe

Or 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.secret

The 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#

stripeStripe-Signature
Signs timestamp.body; any v1 entry may match. The t= timestamp must be within the tolerance (default 5 minutes).
githubX-Hub-Signature-256
sha256= followed by the hex HMAC of the body.
slackX-Slack-Signature
Signs v0:timestamp:body using X-Slack-Request-Timestamp, which must be within the tolerance (default 5 minutes).
hmacconfigurable
HMAC-SHA256 of the raw body in a header you name, hex or base64, with an optional prefix such as 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.secret

Flags#

--verify-webhookstring
stripe, github, slack or hmac. HTTP tunnels only; cannot be combined with --http2 or --oidc, and ngstone serve rejects it.
--verify-webhook-secret-filestring
File holding the signing secret. Falls back to NGSTONE_WEBHOOK_SECRET.
--verify-webhook-pathstringdefault: every request
Verify every request whose decoded, cleaned path contains this path at a segment boundary (starting at any /), 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 #.
--verify-webhook-tolerancedurationdefault: 5m
Timestamp tolerance for stripe and slack, a whole number of seconds from 1s to 24h.
--verify-webhook-headerstring
Signature header for hmac.
--verify-webhook-encodingstringdefault: hex
hex or base64 for hmac.
--verify-webhook-prefixstring
Prefix before the signature for 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.

ngstone.ymlyaml
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
ngstone.jsonjson
{
"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 signature
401 webhook signature rejected: malformed signature
401 webhook signature rejected: invalid signature
401 webhook signature rejected: timestamp outside tolerance
413 request entity too large
503 webhook verification is busy

Signature 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

Unlike basic auth, which only ever sends a digest, HMAC verification needs the signing secret itself, so the agent sends it to the edge over the TLS control channel when the tunnel binds. It lives only in the edge's memory and is not written to durable storage. Only use this with an edge you operate or trust. With --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.