Home Assistant Add-on

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

Prerequisites

Installation & Webhook Relay authentication

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

Hassio add repo]

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:

Create token]

Configuration options

There are several main configuration options, that include:

Option: Simple 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.

Option: TLS pass-through with DuckDNS

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
}

Option: TLS pass-through with Cloudflare

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.

Option: TLS termination with self-signed certificates

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
}

Launch add-on

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.

Bonus: Webhook Forwarding

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.

FAQ

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
}