Go Webhook Websocket Bridge

A Go server for processing webhooks from Buy Me a Coffee and forwarding them to clients via websockets. (actually you can process any webhooks with secret and x-signature-sha256)

Purpose

This project is designed to be installed on a server with a public IP and allows:

1. Receiving webhooks from Buy Me a Coffee
2. Transmitting webhook content via websockets to authorized clients (e.g., StreamerBot)
3. Managing access through IP authorization

Key Features

• Processing webhooks from Buy Me a Coffee
• Webhook verification via HMAC SHA-256 (take secret from your BMAC webhook page)
• Data transmission through websockets
• Client authorization via IP whitelist
• Simple web page for adding IPs to the whitelist
• TLS encryption support
• Operation behind reverse proxies (Nginx, Caddy) and Cloudflare

Running

Environment Variables Setup

Create a .env file in the project root with the following parameters:

# Server main settings
SERVER_PORT=8080
WEBHOOK_SECRET=your_webhook_secret_from_buy_me_a_coffee
# Define path for your websocket clients
WEBSOCKET_PATH=/ws
# Define path for BMAC webhook
WEBHOOK_PATH=/webhook
# This password is used on /auth page for whitelisting IP
ADMIN_PASSWORD=change_this_password

# TLS settings
TLS_ENABLED=false
TLS_CERT=cert.pem
TLS_KEY=key.pem

# Security settings
BEHIND_PROXY=false
TRUST_CLOUDFLARE=false
IP_WHITELIST=127.0.0.1,::1
# Actually, this is just "token" for websockets.
WHITELIST_PASSWORD=change_this_secret

Launch with Docker Compose

docker-compose up -d

Build and Run without Docker

(don't forget to install go)

# Install dependencies
go mod download

# Build
go build -o webhook-bridge .

# Run
./webhook-bridge

Usage

1. Setting up a webhook in Buy Me a Coffee

1. Log in to your Buy Me a Coffee account
2. Go to the Webhooks section: https://www.buymeacoffee.com/webhooks
3. Click "Create New Webhook"
4. Specify your server URL: https://yourdomain.com/{WEBHOOK_PATH}
5. Select the events you want to track and click "create".
6. Select your newly created webhook
7. Copy the secret key and add it to the WEBHOOK_SECRET env variable

2. Client Authorization

1. Open in your browser: https://yourdomain.com/auth
2. Enter the administrator password (from the ADMIN_PASSWORD variable)
3. After successful authorization, your IP will be added to the whitelist
4. Use the obtained websocket URL for connection

3. Connecting to the websocket

The websocket is available at: ws://yourdomain.com/ws/your_token/your_ip (you will obtain this URL in the previous step)

Where your_token is the value from the WHITELIST_PASSWORD variable.

Setting up behind a proxy

If you're hosting the server behind a reverse proxy (e.g., Nginx, Caddy) or/and Cloudflare, you need to properly configure the environment variables:

# Proxy settings
BEHIND_PROXY=true       # Enable proxy mode
TRUST_CLOUDFLARE=false  # Trust the CF-Connecting-IP header (true if using Cloudflare)

IMPORTANT: Caddy v2 sets own X-Forwarded- headers by default. But Nginx does not. In your nginx config you can do something like:

proxy_set_header X-Real-IP        $remote_addr;
proxy_set_header X-Forwarded-For  $remote_addr;

P.S. - If you use Cloudflare, just set TRUST_CLOUDFLARE to true and everything will be fine.

How it works:

1. When BEHIND_PROXY=true:

   • To determine the client's IP, the server checks the X-Forwarded-For and X-Real-IP headers
   • When forming the websocket URL, the wss:// protocol is automatically used (assuming the proxy provides HTTPS)
   • TLS can be disabled on the server itself (TLS_ENABLED=false), as encryption is provided by the reverse proxy

2. If also TRUST_CLOUDFLARE=true:

   • The client's IP is determined by the CF-Connecting-IP header provided by Cloudflare
   • This ensures you get the actual client IP, not the Cloudflare server IP

Example Nginx configuration:

server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws/ {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Security

1. Use HTTPS. PLEASE
2. Change default passwords
3. Use strong and random tokens
4. Configure proxies properly

Why?

I created this project after realizing that the default BMAC OBS notification is completely shit. With this tool, you can get donation events in real-time and create fully custom notifications in OBS with StreamerBot.

Planned

1. • Add redis as a message broker (if there are no websocket connections at the moment)
2. • Add something for whitelist remembering