Webhook Relay agent can run in the background and be managed by the operating system on Linux, Windows and MacOS. To start using the background service, first get the CLI following installation instructions.

Configuration file

When running as a background service, agent needs a configuration file. It’s a simple yaml format file.

For this file, you will need to:

• ​generate access token key and secret.

• ​create a tunnel if you need bidirectional tunnels (optional)

• ​create a bucket if you are going to use one-way webhook forwarding (optional)

Now, populate the file:

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
tunnels:
  - tunnel-1-name
  - tunnel-2-name
buckets:
  - bucket-1-name
  - bucket-2-name

If no tunnels or no buckets are defined, that part of the relay service will be disabled. If no buckets and tunnels are specified, relay service will not start.

Note that you can subscribe to tunnels and buckets even before you have created them through the API/CLI/UI.

Once the relay service starts, key and secret will be encrypted.

Linux

Tu install the service, you will need to use sudo and provide a full path to relay configuration file:

sudo relay service install -c /full/path/config.yaml
sudo relay service start

To specify credentials during install:

sudo relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file

sudo relay service restart

Uninstall

To uninstall the service:

sudo relay service stop
sudo relay service uninstall

To view service logs, use journalctl:

journalctl -u relay.service -f

Windows

Make sure you have download relay CLI and created a config.yaml file.

If you are using Powershell:

.\relay-windows-amd64.exe service install -c .\config.yaml
.\relay-windows-amd64.exe service start 

You can also just keep the config.yaml file in the same directory as relay exe file. Then, you just need to do:

.\relay-windows-amd64.exe service install
.\relay-windows-amd64.exe service start 

The agent is now installed and will be run after a system reboot.

To specify credentials during install:

.\relay-windows-amd64.exe service installl -c .\full\path\config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file):

.\relay-windows-amd64.exe service restart

Uninstall

To uninstall the service:

.\relay-windows-amd64.exe service stop
.\relay-windows-amd64.exe service uninstall

MacOS

Execute as the user who will run the agent:

relay service install -c /full/path/config.yaml -u your-user
relay service start

To specify credentials during install:

relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file):

relay service restart

Uninstall

To uninstall the service:

relay service stop
relay service uninstall

Note: The service needs to be installed from the Terminal by running its GUI interface as your current user. Only then will you be able to manage the service.

Using different region

By default agent connects to EU region. If you are using other region, specify it in the configuration:

version: "v1"
key: your-secret-key
secret: your-secret
region: au # Will use Australia region
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name

Logging

Usually logs can be viewed through journalctl:

journalctl -u relay.service -f

If you are using a Windows machine, then it’s useful to specify a log output location during install:

.\relay.exe service install -c C:\config.yaml  --logs-output C:\relay.log 

You can also specify logging level and output file in the configuration:

version: "v1"
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name
logs_output: /full/path/to/relay-agent-svc.log
log_level: info

Upgrade process

If the executable has write permissions, then to update it you only need to restart the service. Otherwise, follow these steps:

1. Stop the service and uninstall it.

2. Download the new binary following installation instructions for your platform.

3. Install and start the service.

HTTP Proxy settings

Relay can use HTTP proxy to open the tunnel:

version: "v1"
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name
logs_output: /full/path/to/relay-agent-svc.log
log_level: info
http_proxy: http://proxy-hostname:3128

Using with self-hosted Transponder

If you host an instance of Webhook Relay yourself (Transponder), add additional values to specify the server APIs:

version: "v1"
serverAddress: https://example.com
serverGRPCAddress: example.com:9302
serverTunnelAPIAddress: example.com:9800
key: your-secret-key
secret: your-secret
tunnels:
  - tunnel-1-name
buckets:
  - bucket-1-name