Docker container

Prerequisites

• Docker, installation instructions: https://docs.docker.com/engine/install/
• Webhook Relay account, get your token here: https://my.webhookrelay.com/tokens

Forward webhooks

1. Go to https://my.webhookrelay.com/buckets and create a bucket and where you want to forward the webhooks
2. Go to the tokens page and get your access key and secret

export RELAY_KEY=<replace with your key>
export RELAY_SECRET=<replace with your secret>

3. Start a webhookrelayd agent:

docker run -d \
  --name whr-relayd \
  --restart always \
  -e RELAY_KEY=${RELAY_KEY} \
  -e RELAY_SECRET=${RELAY_SECRET} \
  -e BUCKETS=<bucket name> \
  webhookrelay/webhookrelayd:latest

If you are using self-signed certificates on your internal side, specify INSECURE environment variable to skip validation:

INSECURE=true

Subscribe to several buckets or a wildcard

BUCKETS is a comma-separated list of bucket names, bucket IDs or * wildcard patterns:

-e BUCKETS=jenkins*                  # every bucket whose name starts with "jenkins"
-e BUCKETS=jenkins*,github-deploys   # a pattern plus an exact bucket name

• * matches any run of characters, so jenkins* matches jenkins, jenkins-prod and jenkins-pr-123, but not github-jenkins. Use *jenkins* to match the word anywhere in the name.
• A value without * matches only that exact bucket name or ID.
• Buckets created after the agent connects are picked up automatically when their name matches; you do not need to restart or reconfigure the agent.
• Leave BUCKETS unset to subscribe to every bucket in the account.
• The access token's bucket scope still applies. An agent only receives buckets that match both its BUCKETS filter and the token scope, so a pattern cannot widen what a restricted token can stream.
• Each bucket still needs an internal output; buckets with only public outputs are not streamed to agents.

The same patterns work in the buckets: list of a relay run / relay service config file and in the WebSocket subscribe message. relay forward --bucket is different: it takes a single bucket name and creates that bucket if it does not exist, so do not pass a pattern to it.

Open a tunnel

1. Go to https://my.webhookrelay.com/tunnels and create a tunnel with your desired destination
2. Start a bidirectional tunnel:

docker run --name whr-relayd \
  --net host \
  --restart always \
  -d webhookrelay/webhookrelayd:latest \
  --mode tunnel -t mytunnelname -k [access key] -s [access secret]

Here webhookrelayd commands:

• --mode tunnel indicates that it should start bidirectional tunnel
• -t mytunnelname acts as a filter, it has to match the tunnel name that you have created previously
• -k access key is your authentication token key
• -s access secret is your authentication token secret

You can also specify these details through environment variables:

KEY=<your token key>
SECRET=<your token secret>
TUNNELS=<comma separated list of tunnels>
REGION=<region - eu, au, us-west (defaults to eu)>