---
title: "Docker container | WebhookRelay"
meta:
  "og:description": "How to use Webhook Relay client with Docker to start forwarding webhooks to your internal services and open tunnels to expose your services"
  "og:title": "Docker container"
  description: "How to use Webhook Relay client with Docker to start forwarding webhooks to your internal services and open tunnels to expose your services"
---

![Stripes](https://webhookrelay.com/images/stripes.svg)

<details>

<summary>

</summary>

Documentation

**Docker container**

# **Docker container**

How to use Webhook Relay client with Docker to start forwarding webhooks to your internal services and open tunnels to expose your services

## [Prerequisites](#prerequisites)

- Docker, installation instructions: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
- Webhook Relay account, get your token here: [https://my.webhookrelay.com/tokens](https://my.webhookrelay.com/tokens)

## [Forward webhooks](#forward-webhooks)

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

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

1. 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](#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](https://webhookrelay.com/docs/account/access-tokens/) 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](https://webhookrelay.com/docs/installation/autostart-linux/) and in the [WebSocket `subscribe` message](https://webhookrelay.com/docs/webhooks/websocket-server/). `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](#open-a-tunnel)

1. Go to [https://my.webhookrelay.com/tunnels](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)>
```

## **Frequently asked questions**

### **Can a Webhook Relay agent subscribe to all buckets or to buckets matching a wildcard?**

Yes. Set BUCKETS to a * pattern such as jenkins* and the agent receives webhooks from every bucket whose name matches, including buckets created after the agent started, with no restart. Leave BUCKETS unset to subscribe to all buckets the access token is allowed to stream.

Did this page help you?