Hass.io Add-on: Webhook Relay

rusenask · September 30, 2018, 1:58pm

Fast & simple reverse tunnels for your Home Assistant.

About

Webhook Relay addon enables Home Assistant and any other services running inside internal network to receive webhooks from public services such as IFTTT, Zapier, Mailgun or pretty much anything. Add-on also allows you to create bidirectional tunnels for remote access (for example your browser).

It works by opening a connection to the public cloud service and giving you your unique “webhooks inbox” URL which you can supply to 3rd party services or subdomain for remote access.

What this add-on can do?

Integrate with Google Assistant, Alexa, IFTTT.
Remote access to Home Assistant, Node-RED, Configurator, Tileboard GUI (or anything else that can be accessed via browser).
End-to-end TLS encryption for connections from your device.

Webhook Relay is particularly useful when:

You cannot access your router to configure port forwarding
Router doesn’t support port forwarding
Your ISP blocks inbound connections
You don’t have a static IP address
Server that is hosting your home automation system is changing IP, location
You find configuring DuckDNS with Let’s Encrypt too difficult

When Webhook Relay is not useful:

You have a static IP and can configure your router (just point a DNS at it)
Your Home Assistant is already in the public cloud and accessible from anywhere
You can configure DuckDNS with Let’s Encrypt and it works for you, guide here

Quick Start

Before starting the add-on, sign up here.

Installation of this add-on is pretty straightforward and not different in comparison to installing any other Hass.io add-on:

Add our Hass.io add-ons repository URL to your Hass.io instance: https://github.com/webhookrelay/home-assistant
Install the “Webhook Relay” add-on.
Generate token key & secret pair and add it to the add-on’s configuration
Get DuckDNS token and create your domain. Add those details to the “tunnels” config section and “duck_dns” section. Set “accept_terms” to true if you accept Let’s Encrypt ToS.
Set your DuckDNS name and authentication tokens to the configuration and start the “Webhook Relay” add-on.
Check the logs of the “Webhook Relay” add-on to see if everything went well. It should print out your public URL.

Detailed instructions on how to set it up can be found here https://webhookrelay.com/v1/guide/home-automation.html.

Use webhooks forwarding when:

Service that is sending requests to your home automation instance doesn’t expect responses (usually webhook producers don’t expect anything)
Additional security is required for your server and you don’t want to expose it to the internet. Webhooks producer won’t get any information about the server that is consuming your webhooks

You should use tunnels when:

You need remote access to your home automation instance (for example you want to view it through the browser).
Service that is calling your home automation instance wants to receive responses from it.

Plans and Pricing

Webhook Relay is a hosted service that requires infrastructure, support and development time. Our business model is providing a service for a fee. We do not share any of your data with 3rd parties (except Stripe for billing purposes).

Our free plan includes:

One bidirectional tunnel suitable for remote access, due to the lack of HTTPS we wouldn’t recommend using them from unsafe wifi networks.
End-to-end encrypted webhooks forwarding (150 webhooks per month)

For most users basic plan ($4.50/month) will be enough, it includes:

Custom subdomains
Secure TLS pass-through tunnels with auto certificate fetch from DuckDNS (no need for that add-on though)
HTTPS for bidirectional tunnel endpoints
3 tunnels (for example Home Assistant, Node-RED and anything else)
1500 webhooks per month

All plans can be viewed here. Alternative ways to earn HTTPS and custom subdomains:

Blog about it
Tweet about @Webhook Relay
Provide useful feedback

Support

Submit issues to the add-on’s Github repository or send me an email: [email protected]. I try to answer queries as soon as possible

Available since version 2.0

Custom domains through CNAME DNS entries, such as hass.yourdomain.com
TLS pass-through without TLS termination on our side. This will allow Webhook Relay to relay traffic to your Home Assistant without terminating HTTPS. Combined with custom domains this feature will allow you to create fully encrypted tunnels so even if we were forced to, we couldn’t spy on your traffic. It might require a bit more work on your end to setup TLS termination with NGINX/traefik or similar tools though.

balloob · September 30, 2018, 2:09pm

Please note: If you do not set up TLS pass-through (which is not available as of now), webhookrelay.com will be able to access all information that flows through their servers, including your access tokens to access your instance.

rusenask · September 30, 2018, 2:34pm

Correct, although traffic is not recorded/analysed according to our privacy and GDPR policy.

You can still safely use webhooks forwarding as they don’t include any access tokens (I think currently Google Home and Alexa work in the same way?)

dmoses1969 · October 1, 2018, 12:42am

Anyone that’s been unable to access HA remotely due to carrier restrictions should try this.
I installed it over the weekend and it’s working great for me with AT&T LTE. I can finally access my HA installation from my phone on LTE network.

Thanks again for making this!

vlamaranth · January 29, 2019, 10:52pm

Does it work with Home Assistant iOS app?
Is it simple as just pointing the app to the new Webhook domain and go for it?

rusenask · January 29, 2019, 11:32pm

yes, I use it myself with iOS app.

rusenask · January 30, 2019, 10:19am

Good point, I have updated the original post with the changed from the last few months

rusenask · March 11, 2019, 11:47am

Release 2.3.0

Changelog:

Cloudflare support (was initially made available in the previous minor release, however needed more testing)
Various improvements to both DuckDNS and Cloudflare DNS challenge solvers to configure and retrieve certs faster.
Changed how the add-on is built. Removed the HA build step install step, our CI now builds custom images with all the necessary tags and the entrypoint to work with HA out of the box.

Cloudflare integration

You can read full blog post on how to set up the add-on to work with your own custom domains here: https://webhookrelay.com/blog/2019/02/15/cloudflare-support-for-home-assistant/

TL;DR;

Webhook Relay add-on configures your Cloudflare DNS to point to a public tunnel endpoint and configures TLS pass-through tunnel directly to your Home Assistant. Traffic is fully encrypted till it reached your own device where TLS gets terminated. You can also supply your own certs to Home Assistant so even the add-on cannot inspect the traffic.

Next version

Webhook Relay going global! First new regions will be available in Australia and US (currently Webhook Relay tunnels go through EU). Almost nothing really changes from the configuration example, there will be a new field “region”:“au/us/eu” available in the add-on options. Stay tuned

rusenask · March 26, 2019, 8:05pm

Release 2.4.0

Added multi-region support. New regions available in Sydney, Australia and Silicon Valley, US.

If you are using DuckDNS domain with Webhook Relay add-on, then just set the desired region and enjoy fast and low latency access to your Home Assistant. If you are using *.webrelay.io subdomain, a new subdomain will be created for that region. And if you are using Cloudflare with your own domain name - you will have to update CNAME record through your Cloudflare dashboard.

Configuration example when using au region:

{
	"key": "**********",
	"secret": "**********",
	"region": "au",
	"forwarding": [
	],
	"tunnels": [
		{
			"name": "home-assistant", 
			"destination": "http://localhost:8123",
			"protocol": "tls",			
			"domain": "transponder-test.duckdns.org",
			"auto_gen": false
		}
	],
	"duck_dns": {
		"token": "**********",
		"accept_terms": true
	},
	"tunnels_enabled": true,
	"forwarding_enabled": false
}

If you encounter any issues, please let me know

Jorgensen · September 24, 2019, 8:33pm

Hi guys,

I am trying to utilize Webhook Relay in a combination with Owntracks and Hassio. However, I’m struggling to configure the Webhook Relay addon in Hassio. I created a Webhook Relay account and setup a new bucket called “Owntracks”. The default public endpoint, I entered in the Owntracks app on my phone. From the Owntracks integration in Hassio, I got the value for bucket Output. If I force a update in the Owntrack app, I see the request in the Relay logs in the Webhook Relay web interface, and I can see the location data sent. So far so good.

Now I am trying to configure the Webhook Relay Hassio addon. In the config I write

{
  "key": "MyKey",
  "secret": "MySecret",
  "region": "eu",
  "forwarding": [
    {
      "bucket": "Owntracks",
      "destination": "http://127.0.0.1:8123"
    }
  ],
  "tunnels": [
    {
      "name": "home-assistant",
      "destination": "http://127.0.0.1:8123/",
      "protocol": "tls",
      "domain": "example.duckdns.org"
    }
  ],
  "duck_dns": {
    "token": null,
    "accept_terms": false
  },
  "cloudflare": {
    "email": "",
    "api_key": ""
  },
  "tunnels_enabled": false,
  "forwarding_enabled": true
}

but I get the following error

not a valid value for dictionary value @ data['options']. Got {'key': 'MyKey', 'secret': 'MySecret', 'region': 'eu', 'forwarding': [{'bucket': 'Owntracks', 'destination': 'http://127.0.0.1:8123'}], 'tunnels': [{'name': 'home-assistant', 'destination': 'http://127.0.0.1:8123/', 'protocol': 'tls', 'domain': 'example.duckdns.org'}], 'duck_dns': {'token': None, 'accept_terms': False}, 'cloudflare': {'email': '', 'api_key': ''}, 'tunnels_enabled': False, 'forwarding_enabled': True}

I have tried deleting the tunnel and duckdns entries without any luck. I only want simple forwarding of webhooks, remote access is not required. What is wrong with my config?

BR,
Jorgensen

rusenask · September 24, 2019, 8:47pm

Hi Jorgensen,
Yeah, that error validation is not very helpful. Could you try setting

"duck_dns": {
    "token": null,
    "accept_terms": false
  },

to

"duck_dns": {
    "token": "",
    "accept_terms": false
  },

?

Jorgensen · September 24, 2019, 9:01pm

Thanks for the very quick reply. I updated my config with your suggestion, and now the config was saved successfully

Unfortunately, I got a new error when starting the addon, but after some trial and error I got the following config working

{
  "key": "MyKey",
  "secret": "MySecret",
  "region": "dev",
  "forwarding": [
    {
      "bucket": "Owntracks",
      "destination": "http://127.0.0.1:8123"
    }
  ],
  "tunnels": [
    {
      "name": "home-assistant",
      "destination": "http://127.0.0.1:8123/",
      "protocol": "tls",
      "domain": "example.duckdns.org"
    }
  ],
  "duck_dns": {
    "token": "",
    "accept_terms": false
  },
  "cloudflare": {
    "email": "",
    "api_key": ""
  },
  "tunnels_enabled": true,
  "forwarding_enabled": true
}

I don’t understand why I need

"tunnels_enabled": true,

as

"tunnels_enabled": false,

fails to start.

Finally,

"region": "dev",

I would have expected “eu” to work.

Anyway, it seems to work now, and I’ll test for the next couple of days, and get back if I encounter further problems.

Again, thanks a lot!
Jorgensen

rusenask · September 24, 2019, 9:06pm

ah, that’s strange I will check it out and publish a fix when I have a spare minute, sorry for the inconvenience!

Jorgensen · September 24, 2019, 9:08pm

No worries, I have just received the first location update from my phone That’s awesome, now I can get started with my more reliable presence detection.

Thanks!

wrkn · October 13, 2019, 11:30pm

Has anyone got this working with the node-red-contrib-telegrambot config node in webhook mode? Wanted some encouragement before going down that rabbit hole. Thanks!

luichi24h · December 2, 2019, 10:39am

Hi rusensk,
I have it installed on my system, the configuration of the add-on is working fine… but how do i “read” the data in home assistant? I mean what do i need to put in the .yaml file?
trigger…event?.. Can you put an example of what service I need to use to reach the data of the bucket? In the log of the addon i get:
webhook request relayed {“destination”: "http://127.0.0.1:8123,“method”:“POST”,“bucket”:“mybucket”,"status: “405 Method Not Allowed”, “retries”:0}
I am using the free account only to send webhooks without tunnel… In destination in webhooks relay i understand i don’t need to put duckdns and all this things for my case. Right?
Thanks very much for your effort.
Luis

rusenask · December 2, 2019, 7:06pm

Hi @luichi24h, it can forward webhooks to any internal endpoint but there has to be some endpoint that Home Assistant can receive on, currently it seems like it just sends to http://127.0.0.1:8123/ but I imagine it should be something like http://127.0.0.1:8123/.

For example Telegram addon: Telegram webhooks - Home Assistant

Create a bucket
Create an input

Using Telegrams setWebhook method your bot’s webhook URL should be set to https://<public_url>:<port>/api/telegram_webhooks .

Using Telegram’s setWebhook set it to Webhook Relay input endpoint which is something like https://my.webhookrelay/v1/webhooks/<your input ID>
If I understand correctly, you should create a bucket with destination http://127.0.0.1:8123/api/telegram_webhooks and then in the configuration it should look like:

telegram_bot:
  - platform: webhooks
    api_key: YOUR_API_KEY
    parse_mode: html
    allowed_chat_ids:
      - 12345
      - 67890

I will try this myself maybe later this week

xxgmxx · July 18, 2020, 9:34pm

Hi, I really like this idea, but I am not able to get it to work.
My config is :

key: xxxx
secret: xxxx
region: dev
forwarding:
  - bucket: ha
    destination: 'http://192.168.0.103:8123/'
tunnels:
  - name: home-assistant
    destination: 'http://192.168.0.103:8123/'
    protocol: tls
    domain: xxxx.duckdns.org
duck_dns:
  token: xxxx
  accept_terms: true
cloudflare:
  email: ''
  api_key: ''
tunnels_enabled: true
forwarding_enabled: false

[i] region 'dev' configuration selected 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
 [i] Bidirectional tunnelling enabled... 
 [✗] Your plan doesn't include custom subdomains, set 'subdomain' for tunnel 'home-assistant' to an empty string, 
     or upgrade your plan here: https://my.webhookrelay.com/account/plan 
 [i] starting tunneling daemon 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
2020-07-18T20:57:22.117Z	INFO	client starting	{"version": "1.18.3", "tunnels": ["home-assistant"]}
 [i] Webhook forwarding disabled.  
2020-07-18T20:57:22.125Z	INFO	initiating tunnel connection
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
2020-07-18T20:57:22.126Z	INFO	dialing server...	{"network": "tcp", "addr": "tunnel.dev.webrelay.io:443"}
2020-07-18T20:57:22.209Z	ERROR	dial failed	{"network": "tcp", "addr": "tunnel.dev.webrelay.io:443", "err": "x509: certificate is valid for calibre.mersenneprimeltd.com, cloud.mersenneprimeltd.com, mail.mersenneprimeltd.com, mersenneprimeltd.com, mra.mersenneprimeltd.com, pinecloud.mersenneprimeltd.com, plex.mersenneprimeltd.com, privoxy.mersenneprimeltd.com, searx.mersenneprimeltd.com, test.mersenneprimeltd.com, vault.mersenneprimeltd.com, wordpress.mersenneprimeltd.com, www.mersenneprimeltd.com, not tunnel.dev.webrelay.io"}
2020-07-18T20:57:22.210Z	ERROR	can't open tunnel connection, retrying...	{"retrying_in": "0s", "error": "x509: certificate is valid for calibre.mersenneprimeltd.com, cloud.mersenneprimeltd.com, mail.mersenneprimeltd.com, mersenneprimeltd.com, mra.mersenneprimeltd.com, pinecloud.mersenneprimeltd.com, plex.mersenneprimeltd.com, privoxy.mersenneprimeltd.com, searx.mersenneprimeltd.com, test.mersenneprimeltd.com, vault.mersenneprimeltd.com, wordpress.mersenneprimeltd.com, www.mersenneprimeltd.com, not tunnel.dev.webrelay.io"}

I do not really understand what is wrong, could you please help me?

rusenask · July 18, 2020, 10:08pm

Hi, could you please remove line region: dev? If you are based in US, then please set it to region: us-west and au if you are close to Australia. By default it connects to eu region which is hosted in Belgium.

xxgmxx · July 20, 2020, 7:45pm

Thanks, the error is gone,
Now I get this:

::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
 [i] Bidirectional tunnelling enabled... 
 [✗] Your plan doesn't include custom subdomains, set 'subdomain' for tunnel 'home-assistant' to an empty string, 
     or upgrade your plan here: https://my.webhookrelay.com/account/plan 
 [i] starting tunneling daemon 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
 [i] Webhook forwarding disabled.  
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
2020-07-20T19:25:11.412Z	INFO	client starting	{"version": "1.18.3", "tunnels": ["home-assistant"]}
2020-07-20T19:25:11.415Z	INFO	initiating tunnel connection
2020-07-20T19:25:11.415Z	INFO	dialing server...	{"network": "tcp", "addr": "tnl.webrelay.io:9800"}
2020-07-20T19:25:11.837Z	INFO	tunnel proxy configuration updated

If I enable “forwarding” I get also the URL, but it opens a blank page in browser, I have to be missing something, right?

::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
 [i] Bidirectional tunnelling enabled... 
 [✗] Your plan doesn't include custom subdomains, set 'subdomain' for tunnel 'home-assistant' to an empty string, 
     or upgrade your plan here: https://my.webhookrelay.com/account/plan 
 [i] starting tunneling daemon 
2020-07-20T19:36:22.115Z	INFO	client starting	{"version": "1.18.3", "tunnels": ["home-assistant"]}
2020-07-20T19:36:22.117Z	INFO	initiating tunnel connection
2020-07-20T19:36:22.117Z	INFO	dialing server...	{"network": "tcp", "addr": "tnl.webrelay.io:xxxx"}
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
 [i] One-way webhook forwarding enabled... 
 [✓] Forwarding 'ha' configured, URL: 
     https://my.webhookrelay.com/v1/webhooks/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx -> http://192.168.0.103:8123/ 
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: ::: 
2020-07-20T19:36:22.453Z	INFO	using standard transport...
2020-07-20T19:36:22.646Z	INFO	tunnel proxy configuration updated
2020-07-20T19:36:23.289Z	INFO	webhook relay ready...	{"host": "my.webhookrelay.com:xxxx", "buckets": ["ha"]}
2020-07-20 19:36:23.390	INFO	webhook request relayed	{"destination": "http://192.168.0.103:8123/", "method": "GET", "bucket": "ha", "status": "200 OK", "retries": 0}
2020-07-20 19:36:23.430	INFO	webhook request relayed	{"destination": "http://xxxxxxx.webrelay.io", "method": "GET", "bucket": "ha", "status": "412 Precondition Failed", "retries": 0}
2020-07-20 19:36:56.544	INFO	webhook request relayed	{"destination": "http://192.168.0.103:8123/", "method": "GET", "bucket": "ha", "status": "200 OK", "retries": 0}
2020-07-20 19:36:56.575	INFO	webhook request relayed	{"destination": "http://xxxxxxx.webrelay.io", "method": "GET", "bucket": "ha", "status": "412 Precondition Failed", "retries": 0}

What is wrong now? I have been trying to find some tutorials, but I did not find any useful.