// open source · MIT · fully vibecoded

HOOKER

A webhook relay for developers who are tired of exposing their localhost to the internet like some kind of degenerate.

install hooker — bash

# install the CLI (requires Go 1.23+)

$ go install github.com/1slam10/hooker/cmd/hooker@latest

# connect to your relay server

$ hooker connect \

$ --server grpc.hooker.islamadilkhan.me:443 \

$ --token <your-token> \

$ --forward http://localhost:8080 --tls

✓ connected to relay server

✓ forwarding webhooks → http://localhost:8080

⚡ waiting for incoming hooks...

// architecture

HOW THE HOOKER WORKS

Your partner sends a webhook to your public VPS. The server catches it, holds it (or doesn't, depending on your moral flexibility), and streams it down a persistent gRPC tunnel to your local machine. No port forwarding. No ngrok account. No dignity required.

partner

HTTP POST

──▶

your VPS
hooker-server

──▶

gRPC stream

bidirectional

──▶

your laptop

hooker CLI

──▶

local app

localhost:8080

* The CLI initiates the outbound connection — no inbound ports needed on your local machine. In sync mode, your local app's response is relayed back to the original caller. Spicy.

// quickstart

DEPLOY IN 3 STEPS

If you need more than 5 minutes to get this running, touch grass and come back.

Deploy the server on your VPS

SSH into your box and grab the deploy files. The Docker image is pre-built and waiting.

# create a home for your hooker
mkdir ~/hooker && cd ~/hooker

# grab deploy files
curl -sO https://raw.githubusercontent.com/1slam10/hooker/main/deploy/docker-compose.yaml
curl -sO https://raw.githubusercontent.com/1slam10/hooker/main/deploy/config.yaml

# generate tokens — one per endpoint
openssl rand -hex 32

# edit config (see Config section below)
nano config.yaml

# launch
docker compose up -d

Install the CLI on your local machine

Requires Go 1.23+. If you don't have Go installed, maybe webhooks aren't your biggest problem right now.

go install github.com/1slam10/hooker/cmd/hooker@latest

Connect and start receiving

Run the CLI, point it at your server and your local app. A full terminal UI opens — inspect every incoming webhook in glorious detail.

hooker connect \
  --server grpc.hooker.islamadilkhan.me:443 \
  --token  <token-from-config.yaml> \
  --forward http://localhost:8080 \
  --tls

Tell your partner their webhook URL is:

https://http.hooker.islamadilkhan.me/hooks/<your-endpoint>

// configuration

CONFIG THAT DOESN'T SUCK

One YAML file. No env files. No 14 environment variables named WEBHOOK_RELAY_SERVER_HTTP_PORT_NUMBER_VALUE.

# config.yaml — minimal example
endpoints:
  - id: "kaspi"
    path_prefix: "/hooks/kaspi"
    token: "your-openssl-rand-hex-32-output"
    mode: "async"   # or "sync" if you need the response back

  - id: "stripe"
    path_prefix: "/hooks/stripe"
    token: "another-token"
    mode: "sync"
    sync_timeout: 30s

async mode

Server returns 200 immediately and forwards in the background. Your partner is happy. Your local app is irrelevant. Classic.

sync mode

Server holds the connection open, waits for your local app's response, relays it back. For challenge/verification flows where the partner expects an actual response.

tls config

TLS is handled by Nginx upstream. Set tls.enabled: false in config and let your reverse proxy deal with certificates like an adult.

tui navigation

j/k or arrows to navigate · Tab to switch panels · / to filter · color-coded by status: green 2xx, yellow 4xx, red 5xx.