Webhook Relay

https://webhookrelay.com/docs/
Admin
Webhook Relay is an enterprise-ready webhook delivery platform that provides secure tunneling,...
Tokens:135,150
Snippets:1,291
Trust Score:8.6
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install and start the service

Source: https://webhookrelay.com/docs/installation/autostart-windows

Run this command to install and start the Webhook Relay service using the configuration file.

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

--------------------------------

### Install ws library

Source: https://webhookrelay.com/docs/tutorials/edge/javascript-app

Installs the ws WebSocket library via npm, which is required for the client example.

```bash
npm i ws
```

--------------------------------

### Set up Webhook Relay with relay CLI

Source: https://webhookrelay.com/docs/webhooks/internal/localhost

Explicit setup for servers and config-as-code: create a bucket, a public input, a named output, and start forwarding. Each output must be named; a second unnamed output in the same bucket fails to create.

```bash
relay bucket create my-app
relay input create --bucket my-app "public endpoint"
relay output create local-app --bucket my-app --destination http://localhost:3000/webhooks
relay forward -b my-app
```

--------------------------------

### Install and start Webhook Relay agent service

Source: https://webhookrelay.com/docs/tutorials/cicd/jenkins-github

Install and start the Webhook Relay agent as a background service using the configuration file.

```bash
relay service install -c /opt/config/webhookrelay/relay.yaml
relay service start
```

--------------------------------

### Install relay service with credentials

Source: https://webhookrelay.com/docs/installation/autostart-linux

Installs the Webhook Relay service while specifying the key and secret during installation.

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

--------------------------------

### Run the example application

Source: https://webhookrelay.com/docs/webhooks/websocket-server

Execute the example app with Node.js. After running, webhooks sent to the public endpoint will be received by the application.

```bash
node app.js
```

--------------------------------

### Install relay client

Source: https://webhookrelay.com/docs/installation/autostart-macos

Downloads and installs the Webhook Relay CLI using the provided script.

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

--------------------------------

### Install service with log output

Source: https://webhookrelay.com/docs/installation/autostart-windows

Use this command to install the service with log output redirected to a file, useful for troubleshooting.

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

--------------------------------

### Start the NextJS dev server

Source: https://webhookrelay.com/docs/tunnels/demoing-your-website

Navigate into the project directory and start the development server. The server runs on http://localhost:3000.

```bash
cd nextjs-blog
npm run dev
```

--------------------------------

### Install relay service

Source: https://webhookrelay.com/docs/installation/autostart-macos

Installs the Webhook Relay service with the specified configuration file and user.

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

--------------------------------

### Download and install relay client

Source: https://webhookrelay.com/docs/installation/autostart-windows

Run this PowerShell command to download and install the Webhook Relay CLI.

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

--------------------------------

### Install relay service

Source: https://webhookrelay.com/docs/installation/autostart-linux

Installs the Webhook Relay service using sudo and providing the full path to the configuration file.

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

--------------------------------

### Install Webhook Relay skill with openclaw

Source: https://webhookrelay.com/docs/clawhub

Use this command to install the Webhook Relay skill from ClawHub. After installation, the agent automatically picks up the skill and can drive the relay CLI and bin API.

```bash
openclaw skills install webhook-relay
```

--------------------------------

### Install all Webhook Relay skills

Source: https://webhookrelay.com/docs/skills-cli

Installs all Webhook Relay skills from the webhookrelay/skills repository into the current project's skills directory.

```bash
npx skills add webhookrelay/skills
```

--------------------------------

### Install Webhook Relay skills globally

Source: https://webhookrelay.com/docs/skills-cli

Installs all Webhook Relay skills globally so every agent on the machine can use them.

```bash
npx skills add webhookrelay/skills -g
```

--------------------------------

### Install Webhook Relay CLI

Source: https://webhookrelay.com/docs/webhooks/internal/localhost

Install the Webhook Relay CLI on macOS/Linux with curl and on Windows PowerShell with iwr. The commands download and execute the official installation scripts.

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

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

--------------------------------

### Install webhookrelay-ws-client via npm

Source: https://webhookrelay.com/docs/webhooks/websocket-server

Install the Webhook Relay JavaScript SDK from npm. The library can only subscribe to buckets; it cannot create, update, or delete them.

```bash
npm i webhookrelay-ws-client
```

--------------------------------

### Example application using WebhookRelayClient

Source: https://webhookrelay.com/docs/webhooks/websocket-server

Complete example app that reads RELAY_KEY and RELAY_SECRET from environment, subscribes to the 'nodered' bucket, connects, and disconnects after 10 seconds. The handler logs incoming webhook data.

```javascript
// app.js
var ws = require(`webhookrelay-ws-client`);
 
var apiKey = process.env.RELAY_KEY;
var apiSecret = process.env.RELAY_SECRET;
 
var handler = function (data) {
    console.log(data)
}
 
var run = function () {    
    var client = new ws.WebhookRelayClient(apiKey, apiSecret, ['nodered'], handler)
    client.connect();
 
    // do some work
 
    // disconnect whenever connection is no longer needed
    setTimeout(function(){ 
        console.log('disconnecting')
        client.disconnect();
    }, 10000);
}
 
run();
```

--------------------------------

### Start Docker Compose

Source: https://webhookrelay.com/docs/installation/docker-compose

Command to start the Docker Compose services in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Run the JavaScript client

Source: https://webhookrelay.com/docs/tutorials/edge/javascript-app

Starts the client application with node directly.

```bash
node client.js
```

--------------------------------

### Set environment variables for example app

Source: https://webhookrelay.com/docs/webhooks/websocket-server

Export the token key and secret as environment variables RELAY_KEY and RELAY_SECRET. These are used by the example application to authenticate.

```bash
export RELAY_KEY=[YOUR TOKEN KEY]
export RELAY_SECRET=[YOUR TOKEN SECRET]
```

--------------------------------

### Install a single Webhook Relay skill with --skill

Source: https://webhookrelay.com/docs/skills-cli

Installs only the webhook-debug skill from the Webhook Relay skills repository. This skill requires nothing but curl.

```bash
npx skills add webhookrelay/skills --skill webhook-debug
```

--------------------------------

### Example input and output for the enrichment function

Source: https://webhookrelay.com/docs/tutorials/transform/enrich-webhooks

Example input webhook and the corresponding output after the function runs. The input specifies a pet and quantity; the output shows the enriched message with the total price calculated from the API data.

```json
{
  "pet": "cat",
  "quantity": 3
}
```

```json
{
    "action": "purchased",
    "message": "Purchased pet: cat | quantity: 3 | total:150"
}
```

--------------------------------

### Install Atlantis Helm chart with configuration

Source: https://webhookrelay.com/docs/tutorials/cicd/terraform-atlantis

Installs the Atlantis Helm chart version 3.12.2 with required settings for GitHub user, token, secret, service type, ingress, and organization whitelist. Replace the placeholder values with your own.

```bash
helm upgrade --install atlantis stable/atlantis --version 3.12.2 \
  --set=github.user=rusenask \
  --set=github.token=XXX \
  --set=github.secret=very-secret \
  --set=service.type=ClusterIP \
  --set=ingress.enabled=false \
  --set=orgWhitelist="github.com/webhookrelay/*"
```

--------------------------------

### Forwarding configuration output

Source: https://webhookrelay.com/docs/tutorials/cicd/jenkins-github

Example output showing the public endpoint created by the relay forward command.

```text
...
Forwarding configuration created: 
https://vlndyzsibcil98gdte7yp1.hooks.webhookrelay.com -> http://localhost:8080/github-webhook/
```

--------------------------------

### Function deciding based on bucket name (Lua)

Source: https://webhookrelay.com/docs/webhooks/functions/accessing-metadata

Example Lua function that checks the bucket name metadata and makes an HTTP GET request to different endpoints depending on the bucket.

```lua
local http = require("http")

local bucket_name = r.Metadata["bucket_name"]

if bucket_name == "first-bucket" then
  -- do something
  response, err = http.request("GET", "https://company-a.com")
  if err then error(err) end
  -- exit from function
  return
end


if bucket_name == "second-bucket" then
  -- do something
  response, err = http.request("GET", "https://company-b.com")
  if err then error(err) end
  -- exit from function
  return
end
```

--------------------------------

### Try it with Docker: Clone and run the plugin demo

Source: https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin

Commands to clone the plugin repository, build it, and start the demo Jenkins instance with Docker Compose. The demo runs on http://localhost:8095.

```text
git clone https://github.com/jenkinsci/webhook-relay-plugin
cd webhook-relay-plugin
mvn -q clean package
docker compose -f demo/docker-compose.yml up --build   # Jenkins on http://localhost:8095
```

--------------------------------

### Function deciding based on bucket name (JavaScript)

Source: https://webhookrelay.com/docs/webhooks/functions/accessing-metadata

Example JavaScipt function that checks the bucket name metadata and makes an HTTP GET request to different endpoints depending on the bucket.

```javascript
const bucketName = r.metadata["bucket_name"]

if (bucketName === "first-bucket") {
    // do something
    const response = http.request("GET", "https://company-a.com")
    // exit from function
    return
}

if (bucketName === "second-bucket") {
    // do something
    const response = http.request("GET", "https://company-b.com")
    // exit from function
    return
}
```

--------------------------------

### Create a NextJS app with npx create-next-app

Source: https://webhookrelay.com/docs/tunnels/demoing-your-website

Run this command to create a new NextJS app using the learn-starter template. It uses npm and the specified example repository.

```bash
npx create-next-app@latest \
  nextjs-blog \
  --use-npm \
  --example "https://github.com/vercel/next-learn/tree/main/basics/learn-starter"
```

--------------------------------

### Example output from running client.js

Source: https://webhookrelay.com/docs/tutorials/edge/javascript-app

Shows the expected console output after sending a webhook to the public input endpoint, including authentication, subscription, and webhook message details.

```bash
$ node client.js
{"type":"status","status":"authenticated","message":"connected successfully, subscribe to buckets"}
{"type":"status","status":"subscribed","message":"subscribed to buckets: 123"}
{"type":"webhook","meta":{"bucked_id":"89e44c32-27ff-4832-8655-8a42d3851b6f","bucket_name":"123","input_id":"ee4ac550-12a4-41a7-837d-dd3356ed1771","input_name":"Default public endpoint"},"headers":{"Content-Length":["15"],"User-Agent":["insomnia/6.0.2"],"Cookie":["__cfduid=dc244a014f0b1e2965544ddb483c3fe1b1525866866"],"Content-Type":["application/json"],"Accept":["*/*"]},"query":"","body":"{\"hi\": \"there\"}","method":"PUT"}
```

--------------------------------

### Install Jenkins operator via Helm

Source: https://webhookrelay.com/docs/tutorials/cicd/kubernetes-operator

Installs the Jenkins operator using Helm with the release name 'jenkins-operator'.

```bash
helm install jenkins-operator jenkins/jenkins-operator
```

--------------------------------

### Make FreeBSD binary executable

Source: https://webhookrelay.com/docs/installation/cli

Give the downloaded FreeBSD binary permissions to execute and update itself.

```bash
sudo chmod +wx /usr/local/bin/relay
```

--------------------------------

### Download FreeBSD binary

Source: https://webhookrelay.com/docs/installation/cli

Download the WebhookRelay CLI binary for FreeBSD. The first command fetches the binary for amd64, the second for i386. Use the appropriate one for your architecture.

```bash
# For amd64
sudo fetch -o /usr/local/bin/relay https://storage.cloud.google.com/webhookrelay/downloads/relay-freebsd-amd64

# For i386
sudo fetch -o /usr/local/bin/relay https://storage.cloud.google.com/webhookrelay/downloads/relay-freebsd-386
```

--------------------------------

### Install Webhook Relay operator with Helm

Source: https://webhookrelay.com/docs/installation/kubernetes

Installs or upgrades the Webhook Relay operator in the default namespace, passing the credentials from the environment variables.

```bash
helm upgrade --install webhookrelay-operator --namespace=default webhookrelay/webhookrelay-operator \
  --set credentials.key=$RELAY_KEY --set credentials.secret=$RELAY_SECRET
```

--------------------------------

### Tunnel scopes examples

Source: https://webhookrelay.com/docs/account/access-tokens

Shows example tunnel scopes: a tunnel name, a wildcard pattern, and a hostname. These restrict which tunnels a token can subscribe to.

```text
customer-demo
production-*
demo.example.com
```

--------------------------------

### Authenticate and test CLI

Source: https://webhookrelay.com/docs/installation/cli

Authenticate the CLI with your token key and secret, then list your buckets. The 'relay bucket ls' command should return your buckets. If the token is restricted to 'Viewer', listing works but commands that change resources do not.

```bash
relay login -k YOUR_TOKEN_KEY -s YOUR_TOKEN_SECRET
relay bucket ls
```

--------------------------------

### Example email webhook payload

Source: https://webhookrelay.com/docs/email

Example JSON payload delivered to your endpoint when an email is received, showing fields like from, subject, headers, and authentication results.

```json
{
  "from": "karolis.rusenas@gmail.com",
  "from_name": "K",
  "recipient": "5519fb0d-997a-46cd-b102-ac990b4c38fa@in.webhookrelay-mail.com",
  "to": ["5519fb0d-997a-46cd-b102-ac990b4c38fa@in.webhookrelay-mail.com"],
  "subject": "prod test",
  "date": "Fri, 26 Jun 2026 11:27:41 +0400",
  "message_id": "C70BE3E7-4B20-4240-A1B8-2D19E0032FFD@gmail.com",
  "text": "helloooo\r\n",
  "headers": {
    "From": "K <karolis.rusenas@gmail.com>",
    "To": "5519fb0d-997a-46cd-b102-ac990b4c38fa@in.webhookrelay-mail.com",
    "Subject": "prod test",
    "Content-Type": "text/plain; charset=us-ascii",
    "Return-Path": "<karolis.rusenas@gmail.com>"
  },
  "spf": "none",
  "dkim": "pass",
  "dmarc": "pass"
}
```

--------------------------------

### Script with relay events --json, --body, and -q

Source: https://webhookrelay.com/docs/email/cli

Scripting examples using --json, --body, and -q. --json emits full event objects; --body emits parsed-email JSON one per line; -q outputs only event IDs.

```shell
# Extract sender + subject of each email
relay events --bucket signups --json | jq '.[].body | fromjson | {from, subject}'

# Stream raw parsed emails
relay events --bucket signups --body

# Only the event IDs (e.g. to feed into `relay inspect`)
relay events --bucket signups -q
```

--------------------------------

### Install Webhook Relay Operator with Helm

Source: https://webhookrelay.com/docs/tutorials/cicd/kubernetes-operator

Add the Webhook Relay Helm repository and install the operator in the jenkins namespace using the credentials set as environment variables.

```bash
helm repo add webhookrelay https://charts.webhookrelay.com
helm repo update
helm upgrade --install webhookrelay-operator --namespace=jenkins webhookrelay/webhookrelay-operator \
  --set credentials.key=$RELAY_KEY --set credentials.secret=$RELAY_SECRET

```

--------------------------------

### Create bucket and add public outputs with Webhook Relay CLI

Source: https://webhookrelay.com/docs/webhooks/public/multiple-destination-urls

Use this CLI snippet to set up a bucket and add multiple public output destinations. It creates a bucket named 'payments' and adds two public outputs: 'primary-api' and 'audit-copy', each with a destination URL. After running, use 'relay bucket inspect payments' to view the bucket's public input endpoint to give to the sender.

```bash
relay bucket create payments

relay output create primary-api \
  --bucket payments \
  --type public \
  --destination https://api.example.com/webhooks

relay output create audit-copy \
  --bucket payments \
  --type public \
  --destination https://audit.example.com/events
```

--------------------------------

### Bucket scopes examples

Source: https://webhookrelay.com/docs/account/access-tokens

Shows example bucket scopes: a specific bucket name, a wildcard pattern, and a bucket ID. These are used to restrict which buckets a token can subscribe to.

```text
payments-prod
payments-*
f71b350b-92de-4c66-a249-b4c543fc50cb
```

--------------------------------

### Make HTTP GET request using http.request in Lua

Source: https://webhookrelay.com/docs/webhooks/functions/make-http-request

Use the http.request function to make a GET request to an external server. The response body is parsed with json.decode.

```lua
-- importing HTTP package
local http = require("http")

-- making HTTP call
response, err = http.request("GET", "https://example.com")
if err then error(err) end

-- parsing response body from the API
local api_response, err = json.decode(response.body)
if err then error(err) end
```
Tokens:
Raw