What is this

This is a simple webhook listener, primarily built for GitLab. It listens for request containing a secret token and executes scripts according to config file. The tool expects a request to be a POST-request, to be in a JSON format, to carry the correct type application/json, to contain a a header with secret token (see $TOKEN_HEADER) and to contain the json path project/$PROJECT_IDENTIFIER.

Config file structure

The config file uses COMMA as a separator, lines are comments if they start with a #. Each line must feature a web_url of the project, the authorization token and the script to be executed. Scripts referenced in the config must be executable.

PROJECT,TOKEN,PATH_TO_SCRIPT

Running standalone with flask-inbuild server

usage: webhook_listener.py [-h] [-i INTERFACE] [-p PORT] [-c C]
Simple Webhook listener

optional arguments:
  -h, --help            show this help message and exit
  -i INTERFACE, --interface INTERFACE
                        Interface to listen on (default: 0.0.0.0)
  -p PORT, --port PORT  Port to listen on (default: 5000)
  -c C                  Config for handling of webhooks (default:
                        webhook.config)

Running with waitress (WSGI)

waitress-serve --host 127.0.0.1 --port 5000 --call 'app:createApp'

Running behind NGINX for SSL

You can (and should) run this tool behind a reverse proxy handling SSL. I recommend nginx with this configuration. Note the proxy_next_upstream-directive which tells nginx, that it should only report a timeout as bad gateway, since the backend will respond with certain error codes to ease debugging.

server {
    listen 443 ssl;
    location / {
        proxy_pass http://localhost:5184;
    }

    proxy_next_upstream timeout;
}

Response Codes

400 - project not identified in request

The field project/$PROJECT_IDENTIFIER doesn't exist in the request.

401 - project not identified in config

The projects identification was found in the request, but not in the config file.

402 - secret token not found in request

The header with the name specified in $TOKEN_HEADER doesn't exist.

403 - secret token found but is mismatch

The project was found in the configuration and the correct header exists, but the header is either empty or the content (the token) of the header doesn't match the token specified in the configuration file.

More Examples

Have a look at my CI-Scripts and config for more examples on how to work with this tool.

Contribution & Feature-Requests

Contributions and feature requests are welcomed but must retain the spirit of this been a simple solution for simple problems.

simple-webhook-handler/README.md