Webhook Relay for home automation addons work exactly the same as our CLI or webhookrelayd tunneling daemon. These local agents create a reverse tunnel back to the https://my.webhookrelay.com cloud service. Any HTTP requests received by the public endpoints will be routed to your private endpoints. Webhook Relay provides end-to-end encryption, both tunnel and public endpoints use HTTPS for webhook forwarding. If you are using tunnels, HTTPS is optional (defaults to enabled) for all paid plans.
Webhook Relay addon helps to receive webhooks by popular services such as IFTTT or Zapier and relay them to your Home Assistant or Node-RED instances. It can also be used for remote access if you are using tunnels. Since webhooks are just a standard HTTP requests, any services can easily produce and consume them. 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
- 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 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.
Like with any technology, some knowledge about Webhook Relay offered features is required. First of all, applications usually set cookies or JWT tokens. It is important to keep this information secure and you should not use HTTP (non-HTTPS) tunnels for this. Make sure:
- You use TLS pass-through tunnels with your own certificates (add-on can generate Let’s Encrypt certificates for DuckDNS or generate self-signed ones).
- You expose only those services that need to be exposed. Use webhook forwarding functionality when the server doesn’t have to respond (for example you are receiving webhooks and don’t need remote access via your browser).
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.
The 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.
- 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:
Install the add-on by adding https://github.com/webhookrelay/home-assistant repository to your add-ons:
Get DuckDNS token and create your domain. Add those details to the “tunnels” config section and “duck_dns” section.
Addon will need to authenticate itself to the public service. Go to access tokens page and create a new token key & secret pair:
Now, add key and secret into your add-on configuration:
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.
Add-on supports several ways of dealing with domains and TLS termination. Here are several examples of different modes.
TLS pass-through tunnel with Home Assistant decrypting/encrypting traffic and webhook forwarding rule:
Note that in this case you will need to create a CNAME for your tunnel to be correctly routed in your domain provider. Once tunnel is created, visit https://my.webhookrelay.com/tunnels to get your CNAME information.
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:
In case you don’t want 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:
With these tunnels TLS is terminated at Webhook Relay cloud service, however they stay encrypted for the entire time anyway.
Webhook forwarding and tunnel public endponts should be printed out in the add-on’s logs:
- Public endpoint format for webhook forwarding:
https://my.webhookrelay.com/v1/webhooks/<your unique endpoint ID here>
- Public endpoint for tunnels:
If you have any questions or have encountered an issue. Please check Webhook Relay addon logs and supply them here https://github.com/webhookrelay/home-assistant/issues or email us at [email protected]
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: