Docker WebHook Deamon: simple hook server for bash scripts

Diese Seite gibt es auch in Deutsch

Looking for a solution to be able to receive webhooks from certain systems and trigger certain actions, I came across a very simple Docker container. The container executes simple bash scripts, for this it is enough to specify the script name in the URL and pass appropriate variables via the webhooks.

Webhook: what is it?

Certain systems offer the possibility to store webhooks in their settings. Webhooks are HTTP calls that are executed automatically when certain events occur. For example, if a new commit has taken place on a Git server: In this case, a web server can be informed about the new software release via webhook and the new source code can be activated automatically. This is also the purpose for which I use the Docker image presented here.

current version 1.15.1

Technically, the webhook call is a normal HTTP call, accordingly it could be received and processed by any web server with an appropriate route. Mostly it is possible to distinguish between POST and GET when creating the webhooks, as well as usually an access token can be sent along.

Simple webhook server (webhookd) with Docker

Docker Basics

Docker allows applications to be launched by command in a so-called container.
A container is an isolated environment independent of the operating system (OS):
When a container is first launched, Docker independently loads all the necessary sources
from the internet.
Docker can be installed on Windows, macOS or an Linux Distribution
To make the hook server available from the internet and protected with a Let's Encrypt certificate, the following setup is required for the example: Traefik in Docker | multiple web servers incl. certificate SSL

To ensure that webhookd is can be reached securely from the Internet, I use a Let's Encrypt reverse proxy. At first I used Nginx as Reverse-Proxy, but later replaced it with Traefik. The reverse proxy provides an encrypted HTTPS connection and makes it possible to run multiple websites on one server.

Step by step webhookd and Docker including access from the internet

Hardware requirement:
  1. Almost any hardware can be used for the Docker installation: For example, a virtual server of a provider, or for home: a PC, notebook, Raspberry PI, MAC, a NAS: QNAP, Synology or any other hardware on which Windows or Linux can be installed.
Internet access requirements:
  1. The secure access from the Internet is best done via a domain with a DNS entry to the public IP addres, see Domain and its management. In the case of a rented server from a provider, the provider assigns an IP address. If you want to operate a server in your own home network, you need to set up port forwarding.
  2. For the certificate management and access to the web services I use a reverse proxy and Let's Encrypt certificates.

  1. create and customize docker-compose.yml
  2. start container and
  3. execute bash scripts


To start the webhook-Container using docker compose, the Docker image can be downloaded, created and started using a simple docker-compose.yml file. The file can be filled with any text editor as follows and then customized:

Filename: docker-compose.yml, Content:

version: "3.5"
    hostname: webhookd
    image: ncarlier/webhookd:latest
    container_name: webhookd
     - "80"
    #For direct test access, remove "#" in the following 2 lines. Call: http://localhost:83 or http://ServerIP:83
      #- "83:80" 
    restart: always
      WHD_LISTEN_ADDR: ":80"
      WHD_SCRIPTS: /scripts
      WHD_HOOK_TIMEOUT: '600'

  #Labels for ReverseProxy, see:
      - "traefik.enable=true"
      - "traefik.http.routers.webhookd.rule=Host(`hook.domain.tld`)"   
      - "traefik.http.routers.webhookd.entrypoints=web" 
      - "traefik.http.routers.webhookd.entrypoints=websecure"
      - "traefik.http.routers.webhookd.tls.certresolver=myresolver"  
     - ./scripts:/scripts
     - /var/run/docker.sock:/var/run/docker.sock

#Without using a reverse proxy ( the webproxy network is likely to be missing
#and the following lines can be removed or commented out. Alternatively, the network can be created with "docker network create webproxy".
      name: webproxy

For direct access via IP address or localhost - even without reverse proxy, DNS or public IP - the commented out port setting can be activated for test purposes by removing # in front of “ports:” and -"83:80" .

For Internet access via the Traefik reverse proxythe domain must be replaced in the labels with the previously created DNS entries (in the example:hook.domain.tld).

The example uses bind mounts and not docker volumes to permanently store data.

📢 A new post will probably be linked here on 2022-10-13: Docker Volumes vs Bind Mounts allow push notifications?

Start container

Before starting, the scripts folder is still needed. The command docker-compose up -d starts webhookd

docker-compose up -d

see also:

Running bash scripts from a webhook call

After starting the server, any bash scripts can be stored in the ./scripts folder. If the URL of the hook server is called with the script name as path, the Docker container starts the corresponding bash script:
As an example, the following URL: https://webhook.domain.tld/TestBash on the server would invoke a bash script with the same name, i.e.: ./scripts/
If parameters are passed during the call, they can be used as variables within the bash script: $Variable. The call in the browser would then be able to pass variables via the GET method as follows: https://webhook.domain.tld/TestBash?Variable=Wert. Those who prefer the use of POST can also pass them using the POST call.

So far I have successfully tested the webhookd container with GitLab and Gitea . For GitLab and GitHub a sample script is available, for Gitea I had to create a script myself.

positive Bewertung({{pro_count}})
Rate Post:
{{percentage}} % positive
negative Bewertung({{con_count}})

THANK YOU for your review!

Updated: 2022-10-02 von Bernhard

Top articles in this section

Running Docker Mailserver yourself | a field report
With the help of a suitable Docker image, it is relatively easy to run a mail server yourself. I originally used the integrated mail server of the Host Europe vServer (Plesk) and came across a very simple Docker container while looking for a replacement. The lightweight container provides a mail server without a graphical management interface, but can be managed with a few simple commands. Any email client can be used to send and receive the mails, for this POP3 or IMAP is offered for receiving...

Nextcloud Server Docker | Setup + https: Let's Encrypt [ssl]
To synchronize contacts, appointments, and photos of my NAS, I tested Nextcloud and thus turned my back on other cloud providers for my private data. Thanks to Docker, the installation is easier and more flexible than ever, allowing Nextcloud to run on almost any hardware.

Nginx-LetsEncrypt reverse proxy in practice
In addition to Traefk, the Nginx Proxy Automation project can be used to run multiple web services with corresponding SSL certificates on one server . The setup involves several Docker containers that together provide an Nginx reverse proxy including certificate management and SSL offloading. Once the containers are started via Docker Compose, they take care of serving multiple websites over a common IP and its certificate management: for issuing certificates for new containers and renewing the...

Questions / Comments

By continuing to browse the site, you agree to our use of cookies. More Details