webhook-over-websocket

日本語

A tunnel tool that forwards external webhook requests to a local development server via WebSocket.

Overview

webhook-over-websocket allows you to receive webhooks from external services (e.g. GitHub, Stripe, Slack) on your local development machine without exposing it to the internet directly. It works by establishing a persistent WebSocket connection between a publicly accessible server and the client running locally.

flowchart TD
    A[External Service] -- HTTP --> B["Server<br>/webhook/{channel_id}"]
    B <-->|WebSocket| C["Client<br>(local machine)"]
    C -- HTTP --> D["Local application<br>(e.g. http://localhost:3000)"]

Architecture

Component	Role
Server	Publicly accessible HTTP server. Receives webhooks and forwards them over WebSocket to the connected client. Also exposes a Traefik HTTP Provider endpoint for dynamic routing when running at scale.
Client	Runs on the local machine. Connects to the server via WebSocket, receives webhook payloads, and forwards them to the local application.

Server Endpoints

Endpoint	Description
GET /new	Issues a new channel_id (UUID) for a client to use. ?channel_id= requests a specific ID (1–128 characters of A-Z a-z 0-9 . _ -)
GET /traefik-config	Returns dynamic Traefik routing configuration (HTTP Provider). Memberlist backend only
GET /internal/channels	Returns active channel list (used for peer-to-peer sync in multi-replica deployments). Memberlist backend only
GET /ws/{channel_id}	WebSocket upgrade endpoint for client connections
ANY /webhook/{channel_id}[/...]	Receives external webhook requests (any HTTP method) and tunnels them to the client
GET /auth/login	(auth mode only) Redirects to the GitHub OAuth consent page
GET /auth/callback	(auth mode only) GitHub OAuth callback; returns a session JWT

Installation

Docker

docker pull ghcr.io/nonchan7720/webhook-over-websocket:latest

Go install

go install github.com/nonchan7720/webhook-over-websocket@latest

Binary download

Download the latest binary for your platform from the Releases page.

Usage

1. Start the server

Run the server on a publicly accessible host:

webhook-over-websocket server --port 8080

Or with Docker:

docker run --rm -p 8080:8080 ghcr.io/nonchan7720/webhook-over-websocket:latest server --port 8080

Server flags:

This is the beginning of the README. Read the rest at the original. Read the full README ↗