Webhook Relay
Search…
🛠
Installation
📝
Examples
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:
1
http:
2
# ...
3
# Your other settings
4
# ...
5
use_x_forwarded_for: true
6
trusted_proxies:
7
- 0.0.0.0/0 # Allow all addresses (secure when internal)
8
- 172.30.33.0/24 # In case you want to allow only from specific address
Copied!
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
Add-on 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:
- 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:1
{
2
"key": "[YOUR TOKEN KEY]",
3
"secret": "[YOUR TOKEN SECRET]",
4
"forwarding": [],
5
"tunnels": [{
6
"name": "https-tunnel",
7
"destination": "https://127.0.0.1:9300",
8
"protocol": "https",
9
"subdomain": "[YOUR SUBDOMAIN]"
10
}],
11
"duck_dns": {
12
"token": "",
13
"accept_terms": false
14
},
15
"cloudflare": {
16
"email": "",
17
"api_key": ""
18
},
19
"tunnels_enabled": true,
20
"forwarding_enabled": false
21
}
Copied!
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:
1
{
2
"key": "[YOUR TOKEN KEY]",
3
"secret": "[YOUR TOKEN SECRET]",
4
"forwarding": [
5
{
6
"bucket": "ha",
7
"destination": "http://homeassistant:8123"
8
}
9
],
10
"tunnels": [
11
{
12
"name": "home-assistant",
13
"destination": "http://127.0.0.1:8123/",
14
"protocol": "tls",
15
"domain": "your-duckdns-domain.duckdns.org"
16
}
17
],
18
"duck_dns": {
19
"token": "[YOUR DUCKDNS TOKEN]",
20
"accept_terms": true
21
},
22
"cloudflare": {
23
"email": "",
24
"api_key": ""
25
},
26
"tunnels_enabled": true,
27
"forwarding_enabled": false
28
}
Copied!
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.
- 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:
1
{
2
"key": "[YOUR TOKEN KEY]",
3
"secret": "[YOUR TOKEN SECRET]",
4
"forwarding": [
5
6
],
7
"tunnels": [{
8
"name": "home-assistant",
9
"destination": "http://127.0.0.1:8123/",
10
"protocol": "tls",
11
"domain": "home-assistant.example.com",
12
"provider": "cloudflare"
13
}],
14
"duck_dns": {
15
"token": "",
16
"accept_terms": false
17
},
18
"cloudflare": {
19
"email": "[email protected]",
20
"api_key": "[YOUR CLOUDFLARE API KEY]"
21
},
22
"tunnels_enabled": true,
23
"forwarding_enabled": false
24
}
Copied!
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:
1
{
2
"key": "[YOUR TOKEN KEY]",
3
"secret": "[YOUR TOKEN SECRET]",
4
"forwarding": [],
5
"tunnels": [{
6
"name": "customdomain",
7
8
"domain": "ha.keel.sh",
9
"destination": "https://127.0.0.1:8123",
10
"protocol": "tls",
11
"cert_file": "tls.crt",
12
"key_file": "tls.key",
13
"auto_gen": true
14
15
}],
16
"cloudflare": {
17
"email": "",
18
"api_key": ""
19
},
20
"duck_dns": {
21
"token": "",
22
"accept_terms": false
23
},
24
"tunnels_enabled": true,
25
"forwarding_enabled": true
26
}
Copied!
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:
1
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::
2
3
[i] Bidirectional tunnelling enabled...
4
5
[✓] Tunnel 'HA' configured, URL:
6
https://ilklftdwwppnhg7p3ji9zi.webrelay.io -> http://localhost:8123
7
8
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::
9
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::
10
11
[i] One-way webhook forwarding enabled...
12
13
[✓] Forwarding 'ha' configured, URL:
14
https://my.webhookrelay.com/v1/webhooks/bc1a8f18-71e0-4ebb-b66f-cfe2c3060894 -> http://localhost:8123
15
16
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::
Copied!
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:1
{
2
"key": "[YOUR TOKEN KEY]",
3
"secret": "[YOUR TOKEN SECRET]",
4
"forwarding": [],
5
"tunnels": [
6
{
7
"name": "home-assistant",
8
"destination": "https://127.0.0.1:8123",
9
"protocol": "tls",
10
"subdomain": "[YOUR SUBDOMAIN]",
11
}
12
],
13
"cloudflare": {
14
"email": "",
15
"api_key": ""
16
},
17
"duck_dns": {
18
"token": "",
19
"accept_terms": false
20
},
21
"tunnels_enabled": true,
22
"forwarding_enabled": false
23
}
Copied!
Last modified 9mo ago
Copy link
Contents
Prerequisites
Installation & Webhook Relay authentication
Generate Webhook Relay token
Configuration options
Option: Simple HTTPS
Option: TLS pass-through with DuckDNS
Option: TLS pass-through with Cloudflare
Option: TLS termination with self-signed certificates
Launch add-on
Bonus: Webhook Forwarding
FAQ