Webhook Relay agent can run in the background and be managed by the operating system on MacOS, Windows and Linux.

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 for exposing web servers
• create a bucket for webhook forwarding

Open PowerShell:

Download and install the relay client:

iwr https://my.webhookrelay.com/webhookrelay/downloads/install-cli.ps1 -useb | iex

You should see the following output:

Now, create a file config in the C:\ProgramData\WebhookRelay directory:

With contents (get your key and secret from here):

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
buckets:
- windows-bin

Then, install and start the service:

relay service install -c 'C:\ProgramData\WebhookRelay\config.txt'

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

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

relay service restart

• To view the logs:

relay service install -c C:\ProgramData\WebhookRelay\config.txt  --logs-output C:\ProgramData\WebhookRelay\relay.log 

• If the service is not starting, check the logs in C:\ProgramData\WebhookRelay\relay.log

Download and install the relay client:

curl https://my.webhookrelay.com/webhookrelay/downloads/install-cli.sh | bash

Create a config file in /etc/webhookrelay/config.yaml:

sudo mkdir -p /etc/webhookrelay

With contents (get your key and secret from here):

vim /etc/webhookrelay/config.yaml

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
buckets:
- my-bin

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

sudo relay service install -c /etc/webhookrelay/config.yaml

To specify credentials during install:

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

To view service logs, use journalctl:

journalctl -u relay.service -f

Download and install the relay client:

curl https://my.webhookrelay.com/webhookrelay/downloads/install-cli.sh | bash

Create a config file in /etc/webhookrelay/config.yaml:

sudo mkdir -p /etc/webhookrelay

With contents (get your key and secret from here):

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
buckets:
- my-bin

To install the service provide a full path to relay configuration file:

relay service install -c /etc/webhookrelay/config.yaml -u your-user

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

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 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

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.

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

Retry settings can be specified in the configuration file:

version: "v1"
key: your-secret-key
secret: your-secret
buckets:
  - bucket-1-name
relayer:
  retryMax: 10
  retryWaitMin: 30s # Can be 10m, 1h, etc
  retryWaitMax: 1m  # Max wait on the exponential backoff

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

When running relay client as a background service, you will need to pre-create tunnels and forwarding configuration. The client in this mode is not creating them automatically.
To get your access key & secret, visit token page and generate one.

Minimal configuration example:

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
tunnels:
  - my-spacex-tunnel
buckets:
  - tesla-gigafactory-one

Additional configuration can be provided:.

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret  # will be encrypted on startup
forwardingTransport: websocket # default is GRPC, however you can switch to WebSocket
serverAddress: https://my.webhookrelay.com:443
logs_output: /var/log/relay.log # where to write logs
log_level: error # debug/info/warning/error
tunnels:
  - my-spacex-tunnel
buckets:
  - tesla-gigafactory-one
destination: output-name # Or ID or destination URL