msav/webhook-forge repository overview

Webhook Forge is a lightweight HTTP server written in Go that accepts webhook requests and creates flag files when triggered. It provides a simple solution for integrating systems through webhooks, making it perfect for automation workflows and CI/CD pipelines.

⁠Key Features

• Webhook Management API: Create, list, update, and delete webhooks via REST API
• Secure Authentication: Token-based security for both admin operations and webhook invocations
• Flag File Creation: Creates empty files at specified paths when webhooks are triggered
• Flexible Configuration: Customizable through environment variables or config file
• Structured Logging: JSON or text format with rotation capabilities
• Reverse Proxy Support: Can be deployed behind a reverse proxy in a subdirectory

⁠Quick Start

docker pull msav/webhook-forge:latest
docker run -p 8099:8099 -v $(pwd)/config:/app/config -v $(pwd)/data:/app/data -v $(pwd)/logs:/app/logs msav/webhook-forge

⁠Environment Variables

• SERVER_HOST: Host address to bind to
• SERVER_PORT: Port to listen on (default: 8099)
• SERVER_BASE_PATH: Base path for all routes (useful for reverse proxy setups)
• SERVER_ADMIN_TOKEN: Admin authentication token
• HOOKS_STORAGE_PATH: Path to store webhook configurations
• HOOKS_FLAGS_DIR: Directory for created flag files
• LOG_LEVEL: Logging level (debug, info, warn, error)
• LOG_FORMAT: Log format (json or text)
• LOG_FILE_PATH: Path to log file
• LOG_MAX_SIZE: Maximum size of log files before rotation
• LOG_MAX_BACKUPS: Number of rotated log files to keep

⁠Docker Compose Example

version: '3.8'
services:
  webhook-forge:
    image: msav/webhook-forge:latest
    container_name: webhook-forge
    restart: unless-stopped
    ports:
      - "8099:8099"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - SERVER_ADMIN_TOKEN=your-secure-token-here

⁠Volumes

• /app/config: Configuration files directory
• /app/data: Data storage directory
• /app/logs: Log files directory

⁠Health Check

The container includes a health check endpoint at /health to verify service availability.

⁠Basic Usage

1. Create a webhook (requires admin token):

   curl -X POST http://localhost:8099/api/hooks \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer admin-token" \
     -d '{"id": "deploy", "token": "secret-token", "flag_file": "deploy_trigger.txt"}'
   

   Copy

2. Trigger the webhook:

   curl -X POST "http://localhost:8099/webhook/deploy?token=secret-token"
   

   Copy

3. This creates a file at /app/data/flags/deploy_trigger.txt which can be used to trigger other processes

⁠Nginx Reverse Proxy Configuration

⁠Basic Setup

server {
    listen 80;
    server_name example.com;

    location /hooks/ {
        proxy_pass http://127.0.0.1:8099/hooks/;
        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;
    }
}

⁠Enhanced Security with IP Restrictions

server {
    listen 80;
    server_name example.com;

    # Allow webhook invocation from anywhere
    location ~ ^/hooks/webhook/ {
        proxy_pass http://127.0.0.1:8099;
        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;
    }

    # Restrict webhook management API to specific IPs
    location ~ ^/hooks/api/ {
        # Allow only specific IP addresses
        allow 192.168.1.100;      # Admin workstation
        allow 10.0.0.0/24;        # Internal network
        deny all;                 # Deny everyone else
        
        proxy_pass http://127.0.0.1:8099;
        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;
    }
}

When using this configuration, set SERVER_BASE_PATH=hooks in your environment variables or configuration file.

⁠Security Recommendations

• Use a strong, randomly generated admin token
• Mount volumes as read-only where possible
• Consider using reverse proxy with IP restrictions for admin API endpoints
• Run the container with limited privileges

⁠Tags

• latest: Most recent stable release
• x.y.z: Specific version releases
• edge: Development builds

⁠License

GNU General Public License v3.0