Docker Webhook

This repository contains a minimalist, secure, and transparent Git Webhook relay built directly from the official source of adnanh/webhook.

It is designed to listen for webhook events (HTTP POST requests) from remote services or Git registries (such as Forgejo, GitHub, or GitLab) and execute local scripts or Docker commands on the host machine in response.

Architecture & Workflow

1. Trigger Event: An external service or Git repository sends a secure HTTP POST request containing a unique token to this relay.
2. Validation: The relay validates the payload, headers, or URL parameters against your predefined rules.
3. Execution: Upon successful validation, the relay executes a corresponding local shell script (e.g., pulling code, running tests, triggering updates, or modifying infrastructure).

Recommended Directory Structure

To maintain a clean and predictable environment, the project should be structured as follows:

/opt/webhook-relay/
├── Dockerfile
├── docker-compose.yml
├── hooks.json            # Define your webhook triggers here
└── scripts/              # Place your custom shell scripts here
    └── your-script.sh

Configuration

1. Dockerfile (Multi-stage Build)

The container compiles the webhook binary directly from source using Go to ensure stability. It stays highly secure by automatically inheriting the latest Alpine Linux base patches during compilation.

2. hooks.json

Define your webhook rules in this file. Thanks to the -hotreload flag used at runtime, hooks.json updates dynamically without restarting the container whenever new hooks are added.

[
  {
    "id": "trigger-custom-action",
    "execute-command": "/scripts/your-script.sh",
    "command-working-directory": "/config",
    "response-message": "Webhook received. Executing script...",
    "trigger-rule": {
      "match": {
        "type": "value",
        "value": "YOUR_SECRET_TOKEN_STRING",
        "parameter": {
          "source": "url",
          "name": "token"
        }
      }
    }
  }
]

3. Custom Scripts (scripts/your-script.sh)

Each hook triggers a standard shell script. Since the host's Docker socket can be passed to the container, these scripts can interact directly with the host system:

#!/bin/sh
echo "==> Webhook triggered successfully <=="

# Add your custom logic here (e.g., git pull, docker compose restart, alerts, etc.)

echo "==> Execution finished! <=="

Setup and Installation

1. Clone this repository to your target server.
2. Ensure your custom shell scripts have execution privileges:

   chmod +x scripts/*.sh
   

3. Boot up the relay locally:

   docker compose up -d --build
   

CI/CD and Automated Builds

This repository is optimized for automated building via CI/CD pipelines (e.g., Forgejo Actions, GitHub Actions). Pipelines can be configured to pull alpine:latest, run an apk upgrade, compile the latest webhook binary, and push it to your private Package Registry automatically.

To pull the updated security image on your server, simply run:

docker compose pull && docker compose up -d

Troubleshooting and Logs

Because this setup relies entirely on native, lightweight components without hidden layers, all events and execution outputs can be monitored directly via standard Docker commands:

docker logs central-webhook-relay -f

Docker Compose example

See the docker-compose.yml file for an example.