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:
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
