Webhook Relay provides a secure, stripped down tunneling daemon webhookrelayd which can be used as a Home Assistant add-on.

• It is advised that you are on a Webhook Relay subscription that supports TLS pass-through tunnels (basic plan is $4.5 per month).
• Your Home Assistant supports TLS termination. For this you can either use nginx proxy or let add-on terminate TLS.

Important! Recent Home Assistant versions require you to set up a trusted_proxies IP list. Webhook Relay add-on must be in the list. Read more in the official Home Assistant documentation

To enable proxying in Home Assistant, edit your configuration.yaml:

http:
  # ...
  # Your other settings
  # ...
  use_x_forwarded_for: true
  trusted_proxies:
    - 0.0.0.0/0      # Allow all addresses (secure when internal)
    - 172.30.33.0/24 # In case you want to allow only from specific address

Install the add-on by adding https://github.com/webhookrelay/home-assistant repository to your add-ons:

Generate Webhook Relay token

Addon will need to authenticate itself to the public service. Go to access tokens page and create a new token key & secret pair:

There are several main configuration options, that include:

• Simple HTTPS tunnels under https://your-subdomain.webrelay.io domain. These tunnels are easiest to configure and provide optimal security level. Even though Webhook Relay does not record the traffic and will never do, consider using TLS pass-through tunnels.
• TLS pass-through tunnels with DuckDNS domains.
• TLS termination with self-signed certificates
• TLS pass-through tunnels with Cloudflare.
• TLS pass-through tunnels with Home Assistant terminating HTTPS.

This is by far the simplest option. You don’t have to register to DuckDNS or you don’t want to use your own domain name, you can create a tunnel under .webrelay.io and use HTTPS tunnels:

{
    "key": "[YOUR TOKEN KEY]",
    "secret": "[YOUR TOKEN SECRET]",
    "forwarding": [],
    "tunnels": [{
        "name": "https-tunnel",
        "destination": "https://127.0.0.1:9300",
        "protocol": "https",
        "subdomain": "[YOUR SUBDOMAIN]"
    }],
    "duck_dns": {
        "token": "",
        "accept_terms": false
    },
    "cloudflare": {
    "email": "",
    "api_key": ""
  },
    "tunnels_enabled": true,
    "forwarding_enabled": false
}

With these tunnels TLS is terminated at Webhook Relay cloud service, however they stay encrypted for the entire time anyway.

This configuration option ensures minimal price and maximum privacy. All traffic going through Webhook Relay servers is fully encrypted and only decrypted on your device. Since DuckDNS is providing free subdomains, you don’t even have to buy one.

Get DuckDNS token and create your domain. Add those details to the “tunnels” config section and “duck_dns” section.

Note that your DuckDNS API token will always remain on the device and will never be shared with Webhook Relay cloud service.

Now, add key, secret and DuckDNS token into your add-on configuration:

{
  "key": "[YOUR TOKEN KEY]",
  "secret": "[YOUR TOKEN SECRET]",
  "forwarding": [
    {
      "bucket": "ha",
      "destination": "http://homeassistant:8123"
    }
  ],
  "tunnels": [
    {
      "name": "home-assistant",
      "destination": "http://127.0.0.1:8123/",
      "protocol": "tls",
      "domain": "your-duckdns-domain.duckdns.org"
    }
  ],
  "duck_dns": {
    "token": "[YOUR DUCKDNS TOKEN]",
    "accept_terms": true
  },
    "cloudflare": {
    "email": "",
    "api_key": ""
  },
  "tunnels_enabled": true,
  "forwarding_enabled": false
}

This configuration option ensures maximum flexibility and privacy. All traffic going through Webhook Relay servers is fully encrypted and only decrypted on your device. Since Cloudflare can manage any DNS records, this option will work for you no matter where you bought your domains.

Important: if you have an existing A record for that domain/subdomain, please first delete it before starting the add-on. CNAME records will be automatically updated.

To get Cloudflare API key, follow official information:

1. Login to the Cloudflare account.
2. Go to My Profile.
3. Scroll down to API Keys and locate Global API Key.
4. Click API Key to see your API identifier.

Note that your Cloudflare API will always remain on the device and will never be shared with Webhook Relay cloud service.

Now, add key, secret, Cloudflare email and Cloudflare API key into your add-on configuration:

{
    "key": "[YOUR TOKEN KEY]",
    "secret": "[YOUR TOKEN SECRET]",
    "forwarding": [

    ],
    "tunnels": [{
        "name": "home-assistant",
        "destination": "http://127.0.0.1:8123/",
        "protocol": "tls",
        "domain": "home-assistant.example.com",
        "provider": "cloudflare"
    }],
    "duck_dns": {
        "token": "",
        "accept_terms": false
    },
    "cloudflare": {
        "email": "[email protected]",
        "api_key": "[YOUR CLOUDFLARE API KEY]"
    },
    "tunnels_enabled": true,
    "forwarding_enabled": false
}

Please note that when using Cloudflare, you need to specify provider: cloudflare for the tunnel.

TLS pass-through tunnel with auto-generated, self-signed certificates from the agent. Home Assistant running simple HTTP. Traffic is encrypted end-to-end and only decrypted on localhost:

{
    "key": "[YOUR TOKEN KEY]",
    "secret": "[YOUR TOKEN SECRET]",
    "forwarding": [],
    "tunnels": [{
        "name": "customdomain",

        "domain": "ha.keel.sh",
        "destination": "https://127.0.0.1:8123",
        "protocol": "tls",
        "cert_file": "tls.crt",
        "key_file": "tls.key",
        "auto_gen": true

    }],
    "cloudflare": {
    "email": "",
    "api_key": ""
  },
    "duck_dns": {
        "token": "",
        "accept_terms": false
    },
    "tunnels_enabled": true,
    "forwarding_enabled": true
}

Now, start the add-on and check the logs. It should print out what tunnels were configured and some additional information when HTTPS certificates are being retrieved.

Webhook forwarding and tunnel public endpoints should be printed out in the add-on’s logs:

::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 

 [i] Bidirectional tunnelling enabled... 

 [✓] Tunnel 'HA' configured, URL: 
     https://ilklftdwwppnhg7p3ji9zi.webrelay.io -> http://localhost:8123 

::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 

 [i] One-way webhook forwarding enabled... 

 [✓] Forwarding 'ha' configured, URL: 
     https://my.webhookrelay.com/v1/webhooks/bc1a8f18-71e0-4ebb-b66f-cfe2c3060894 -> http://localhost:8123 

::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 

You can also view these details in Webhook Relay web UI at https://my.webhookrelay.com/buckets and https://my.webhookrelay.com/tunnels.

• Public endpoint format for webhook forwarding: https://my.webhookrelay.com/v1/webhooks/<your unique endpoint ID here>

Q: Does using Webhook Relay to forward webhooks makes my Home Assistant instance less secure?

A: Using our service makes your Home Assistant more secure, as webhook forwarding is one-way traffic only and no information about your Home Assistant can be retrieved.

Q: Is free plan enough for me?

A: Depends on your usage. If you just want to relay webhooks to your internal Home Assistant server then using free tier should be enough, current limit is 150 webhooks per month. If you want to access it remotely via tunnels, we would recommend to subscribe to a basic plan which is just 4.5$ per month and get secure HTTPS tunnels.

Q: Why are webhooks recorded?

A: Webhook Relay is used by engineers and developers to develop, debug and proxy various webhook requests to other services. Recording enables you to inspect the traffic. Only you or your sub-accounts can access them. Usually webhooks don’t store any sensitive information.

Q: Is tunnel traffic recorded?

A: No, you can view our GDPR policy. Tunnel traffic is not recorded. Also, please use TLS tunnels whenever possible for maximum protection.

Q: Do phone push notifications work with the tunnels?

A: Push notifications are based on HTTP2 standard that requires TLS all the way. It will work if Home Assistant has TLS enabled (you would be accessing it locally over https://192.168.*.*:8123). To do that, you can generate certificates yourself and just supply in the tunnel to not do TLS termination. Example configuration:

{
    "key": "[YOUR TOKEN KEY]",
    "secret": "[YOUR TOKEN SECRET]",
    "forwarding": [],
    "tunnels": [
        {
            "name": "home-assistant", 
            "destination": "https://127.0.0.1:8123",
            "protocol": "tls",            
            "subdomain": "[YOUR SUBDOMAIN]",
        }    
    ],
    "cloudflare": {
    "email": "",
    "api_key": ""
  },
    "duck_dns": {
        "token": "",
        "accept_terms": false
    },
    "tunnels_enabled": true,
    "forwarding_enabled": false
}