Home Automation

How does it work?

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.

What’s the use case?

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 should use webhooks forwarding when:

You should use tunnels when:

Security best practices

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:

Home Assistant

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

Hassio add-on]

Prerequisites

Quick start

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

  1. Add our Hass.io add-ons repository URL to your Hass.io instance: https://github.com/webhookrelay/home-assistant
  2. Install the “Webhook Relay” add-on.
  3. Generate token key & secret pair and add it to the add-on’s configuration
  4. 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.
  5. Start the “Webhook Relay” add-on.
  6. Check the logs of the “Webhook Relay” add-on to see if everything went well. It should print out your public URL:
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::
[i] Bidirectional tunnelling enabled...
[✓] Tunnel 'HA' configured, URL:
https://ilklftdwwppnhg7p3ji9zi.webrelay.io -> http://localhost:8123
::: ::: ::: ::: ::: ::: ::: ::: ::: ::: :::

Adding add-on to your Home Assistant

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

Hassio add repo]

Create DuckDNS domain and get token

Get DuckDNS token and create your domain. Add those details to the “tunnels” config section and “duck_dns” section.

Generate access 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]

Now, add key and secret into your add-on configuration:

{
"key": "your-webhookrelay-key",
"secret": "your-webhookrelay-secret",
"forwarding": [
{
"bucket": "ha",
"destination": "http://homeassistant:8123"
}
],
"tunnels": [
{
"name": "autopilot",
"destination": "http://127.0.0.1:8123/",
"protocol": "tls",
"domain": "your-duckdns-domain.duckdns.org"
}
],
"duck_dns": {
"token": "your-duckdns-token",
"accept_terms": true
},
"tunnels_enabled": true,
"forwarding_enabled": false
}

Now, start the addon and check the logs.

Other configuration examples

Add-on supports several ways of dealing with domains and TLS termination. Here are several examples of different modes.

TLS pass-through with HA doing termination

TLS pass-through tunnel with Home Assistant decrypting/encrypting traffic and webhook forwarding rule:

{
"key": "your-key",
"secret": "your-secret",
"forwarding": [
{
"bucket": "my-ifttt",
"destination": "https://bin.webhookrelay.com/v1/webhooks/7d509cd1-c9aa-48db-ad4d-6a750ee2ggg"
}
],
"tunnels": [
{
"name": "customdomain", // optional tunnel name
"domain": "ha.keel.sh", // optional domain (requires whitelisted domains feature)
"destination": "https://127.0.0.1:8123", // Home Assistant address
"protocol": "tls", // pick between tls/http/https
"cert_file": "", // not set, Home Assistant will terminate TLS
"key_file": "", // not set, Home Assistant will terminate TLS
"auto_gen": false
}
],
"tunnels_enabled": true,
"forwarding_enabled": true
}

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-key",
"secret": "your-secret",
"forwarding": [
{
"bucket": "my-ifttt",
"destination": "https://bin.webhookrelay.com/v1/webhooks/7d509cd1-c9aa-48db-ad4d-6a750ee2ggg"
}
],
"tunnels": [
{
"name": "customdomain", // optional tunnel name
"subdomain": "", // optional subdomain
"domain": "ha.keel.sh", // optional domain (requires whitelisted domains feature)
"destination": "https://127.0.0.1:8123", // Home Assistant address
"protocol": "tls", // pick between tls/http/https
"cert_file": "tls.crt", // TLS certificate
"key_file": "tls.key", // TLS private key
"auto_gen": true // Auto-generate key & cert if doesn't exist
}
],
"tunnels_enabled": true,
"forwarding_enabled": true
}

Public endpoint

Webhook forwarding and tunnel public endponts 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.

Issue reporting & support

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]

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.