Receive webhooks on your
home lab

Webhooks need a public URL

Webhook providers — GitHub, Stripe, Slack, your CI system — need to send HTTP POST requests to your server. But your home lab is behind NAT, your ISP may block inbound ports, and your IP changes every few days.

The usual workarounds are painful: port forwarding, dynamic DNS, reverse proxies, or paying for a cloud VM just to relay a few HTTP requests. HLE webhook tunnels solve this with a single command.

One command

Create a webhook tunnel that forwards incoming requests to your local service:

hle webhook --path /hook/github --forward-to http://localhost:3000/webhook

The CLI prints a public URL like:

https://wh-a3f7b2c9e1d0f485-x7k.hle.world/hook/github

Paste that URL into your webhook provider's settings. Done. Requests to that URL are forwarded to your local service in real time.

How webhook tunnels work

1. You create a webhook tunnel The CLI opens an outbound WebSocket connection to the HLE relay. No inbound ports needed.
2. HLE generates a randomized URL The subdomain includes a 16-character hex token (2⁶⁴ possibilities) — unguessable by design.
3. Provider sends a POST request GitHub, Stripe, or any service sends an HTTP request to your webhook URL.
4. Relay enforces path + rate limit The server checks the request path matches your configured prefix and applies per-tier rate limits.
5. Request is forwarded to your service The request travels through the encrypted tunnel to your local endpoint. Response flows back the same way.

Three layers of protection

Randomized subdomains

Regular tunnels use predictable subdomains like myapp-x7k.hle.world. Webhook tunnels use wh-a3f7b2c9e1d0f485-x7k.hle.world — 16 hex characters that are cryptographically random. An attacker would need to guess 1 out of 18 quintillion possible URLs.

Server-side path enforcement

The relay server only forwards requests that match your webhook path prefix. If you registered with --path /hook/github, requests to /admin or / are blocked with a 404 — they never reach your local service.

Signature verification

HLE secures the transport. But you should also verify that requests actually come from the expected provider. Most webhook services sign their payloads:

Common setups

GitHub → self-hosted Gitea

Mirror push events from GitHub to your Gitea instance:

hle webhook --path /hook/github \
  --forward-to http://localhost:3000/api/v1/repos/mirror/hooks/trigger

In GitHub → Repository Settings → Webhooks → Add webhook, paste the HLE URL as the Payload URL. Set Content type to application/json and add a secret for signature verification.

Stripe → local dev server

Test Stripe webhooks during development without the Stripe CLI:

hle webhook --path /stripe \
  --forward-to http://localhost:4242/webhook

In the Stripe Dashboard → Developers → Webhooks → Add endpoint. Select the events you need (e.g. checkout.session.completed) and paste the HLE URL.

n8n workflow triggers

Receive external triggers for your self-hosted n8n automations:

hle webhook --path /webhook \
  --forward-to http://localhost:5678/webhook

In n8n, create a Webhook node, copy the webhook path, and use the HLE URL with that path as the trigger URL in any external service.

Per-plan limits

Webhook tunnels include rate limiting to protect your services from abuse. Limits scale with your plan:

Rate limit headers are included in every webhook response so your provider can track usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42

When the limit is exceeded, the server returns HTTP 429 with a Retry-After: 60 header. Most webhook providers handle 429 responses gracefully by retrying after the specified delay.

hle webhook vs hle expose

Use hle webhook for automated callbacks from external services. Use hle expose for anything humans will visit in a browser.

Tips