jimurrito/hook-relay repository overview

⁠Hook Relay

Lite webhook request proxy. Allows apps to reduce their attack surface by using this service as a proxy just for WebHooks.

Links:

• Github⁠
• Docker Hub⁠

Table of Contents

• Hook Relay⁠
• Features⁠
• Docker⁠
  • CLI⁠
  • Compose⁠
• Environmental variables⁠
• From source⁠
  • Dependencies⁠
  • Deployment⁠
• Using relay.conf⁠
  • Configuration path⁠
  • Breakdown⁠
• Utilizing Hook-Relay⁠
  • Powershell⁠
  • Bash⁠
  • Async mode⁠
• FAQ⁠
  • Can I nest relays?⁠
  • Is proof_key required?⁠
  • What does Live Reloading mean for this app?⁠
• Any issues?⁠

⁠Features

• Blazingly fast!
• Handles all requests in parallel for maximum throughput.
• Live reloading - never restart the server for configuration changes!
• TOML configuration files.
• Optional async mode for request relaying.
• Small compute foot print.
• Highly scalable.
• Supports vertical and horizontal scaling.
• Multi-Architecture Support. (Coming soon)
• Supports Windows and Linux.

⁠Docker

The Alpine Linux based image was built to have the smallest footprint possible.

⁠CLI

docker run \
  --name hook-relay \
  -p 4000:4000 \
  -v path/to/config/dir:/config \
  jimurrito/hook-relay:latest

⁠Compose

services:
  hook-relay:
    container_name: hook-relay
    ports:
      - 4000:4000
    volumes:
      - path/to/config/dir:/config
    image: jimurrito/hook-relay:latest

See section on Environmental Variables⁠ for more options.

Using the volume mount we setup for /config on the container, the server will check for a file called relay.conf. If this file is not present, one will be created with a default configuration.

Go to the Using relay.conf⁠ section to learn more about the relay.conf file.

⁠Environmental variables

⁠From source

If you need to use this compiled from source, please follow these steps. For ease of use, I highly recommend using the Docker deployment method⁠ above.

⁠Dependencies

• inotify-tools
• Elixir 1.17+
• Erlang OTP 27+

⁠Deployment

# From the root directory of this repo
cd src/
mix deps.get
CONFIG_PATH=path/to/config/dir mix hook_relay

⁠Using relay.conf

This file contains the relay endpoints and targets for the server. The file is formatted using TOML⁠.

The server will generate a default config if not present in the provided directory.

⁠Configuration path

The server will check for the file using the CONFIG_PATH environmental variable. This variable must be a directory, and not the file itself. If you are deploying by docker, you can disregard this as the variable is not configurable.

⁠Breakdown

Here is the default configuration that will be generated by the server:

[relay]
proof_key = "trust-me-bro" 
target = "https://hook-relay.requestcatcher.com/test"
async = false

[relay_async]
proof_key = "trust-me-bro" 
target = "https://hook-relay.requestcatcher.com/test"
async = true

This configuration defines 2 relay endpoints. relay and relay_async. Each relay will have its own endpoint. For example, this configuration will have the server listen on /relay and /relay_async.

For each relay, we see a set of 3 parameters.

• proof_key This is a secret that protects the relay. If unset, authentication will be disabled for the relay endpoint. This must be provided at the root level of the JSON request body used for the webhook. This will be covered more in-depth in Utilizing Hook-Relay⁠.

• target This is the endpoint that the request should be relayed to.

• async This defines whether the relay to the target will be asynchronous or not. If async is enabled, and the request to the relay target fails, only the server logs will indicate the failure. During synchronous mode, the WebHook sending client will be told if the relayed request was successful or not.

Each relay will have it's requests handled in parallel. There is no limit to the amount of relays that can be created.

All 3 parameters are required for each relay declaration.

⁠Utilizing Hook-Relay

Once this is up and running, we can use one of the below examples to test the function of the relay.

The default configuration will relay the requests to both endpoints to https://hook-relay.requestcatcher.com/test⁠. You can use Request Catcher⁠ to test the server with your own URL.

⁠Powershell

$body = @{
  proof_key = "trust-me-bro"
  msg       = "Test Relay"
}
Invoke-WebRequest -Uri http://<URL_to_Server>/relay -Method post -Body $body

Result:

StatusCode        : 200
StatusDescription : OK
Content           : {"result":"relayed"}
RawContent        : HTTP/1.1 200 OK
                    Date: Thu, 06 Feb 2025 02:06:27 GMT
                    Vary: accept-encoding
                    Cache-Control: must-revalidate, max-age=0, private
                    X-Request-ID: GCF8Sa53wsgGb5MAABtH
                    Content-Type: application/json; charset=…
Headers           : {[Date, System.String[]], [Vary, System.String[]], [Cache-Control, System.String[]], [X-Request-ID, System.String[]]…}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 20
RelationLink      : {}

⁠Bash

#!/bin/bash

json_data='{"proof_key": "trust-me-bro", "msg": "Test Relay"}'

curl -X POST \
     -H "Content-Type: application/json" \
     -d "$json_data" \
     http://<URL_to_Server>/relay

Result:

{"result":"relayed"}

⁠Async mode

When async is set to true, the result will be:

{"result":"async_relayed"}

⁠FAQ

⁠Can I nest relays?

No. Relays endpoints will only use the first level of the URL path.

⁠Is proof_key required?

No. You can change proof_key to be unset in the relay.conf file and the parameter will not be checked.

⁠What does Live Reloading mean for this app?

Anytime you make changes to the relay.conf file, the server will automatically reload the configuration. This includes adding and removing relays. Changes are immediate and this feature can not be disabled.

⁠Any issues?

Open an issue on this github repo.