Home Assistant

Webhook Relay provides an add-on for a popular home automation tool.

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

Prerequisites

It is advised that you are on a Webhook Relay subscription that supports TLS pass-through tunnels (basic plan is $4.99 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

Installation & Webhook Relay authentication

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

Generate Webhook Relay token

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

Configuration options

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.

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:

Login to the Cloudflare account.
Go to My Profile.
Scroll down to API Keys and locate Global API Key.
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": "your-email@example.com",
        "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.

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

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
}

PreviousHome Automation NextNode-RED

Last updated 2 years ago