A very simple webhook server to launch shell scripts.

Run the following command:

$ go get -v github.com/ncarlier/webhookd

Or download the binary regarding your architecture:

$ sudo curl -s https://raw.githubusercontent.com/ncarlier/webhookd/master/install.sh | bash

Or use Docker:

$ docker run -d --name=webhookd \
  --env-file .env \
  -v ${PWD}/scripts:/var/opt/webhookd/scripts \
  -p 8080:8080 \
  ncarlier/webhookd

Check the provided environment file .env for configuration details.

Note that this image extends docker:dind Docker image. Therefore you are able to interact with a Docker daemon with yours shell scripts.

You can configure the daemon by:

Webhooks are simple scripts dispatched into a directory structure.

By default inside the ./scripts directory. You can override the default using the APP_SCRIPTS_DIR environment variable.

Example:

/scripts
|--> /github
  |--> /build.sh
  |--> /deploy.sh
|--> /ping.sh
|--> ...

The directory structure define the webhook URL. The Webhook can only be call with HTTP POST verb. If the script exists, the HTTP response will be a text/event-stream content type (Server-sent events).

Example:

The script: ./scripts/foo/bar.sh

#!/bin/bash

echo "foo foo foo"
echo "bar bar bar"

$ curl -XPOST http://localhost/foo/bar
data: foo foo foo

data: bar bar bar

data: done

You have several way to provide parameters to your webhook script:

• URL query parameters and HTTP headers are converted into environment variables. Variable names follows "snakecase" naming convention. Therefore the name can be altered.

  ex: CONTENT-TYPE will become content_type.

• Body content (text/plain or application/json) is transmit to the script as parameter.

Example:

The script:

#!/bin/bash

echo "Query parameter: foo=$foo"
echo "Header parameter: user-agent=$user_agent"
echo "Script parameters: $1"

The result:

$ curl --data @test.json http://localhost/echo?foo=bar
data: Query parameter: foo=bar

data: Header parameter: user-agent=curl/7.52.1

data: Script parameter: {"foo": "bar"}

data: done

By default a webhook has a timeout of 10 seconds. This timeout is globally configurable by setting the environment variable: APP_HOOK_TIMEOUT (in seconds).

You can override this global behavior per request by setting the HTTP header: X-Hook-Timeout (in seconds).

Example:

$ curl -XPOST -H "X-Hook-Timeout: 5" http://localhost/echo?foo=bar

The script's output is collected and stored into a log file (configured by the APP_WORKING_DIR environment variable).

Once the script executed, you can send the result and this log file to a notification channel. Currently only two channels are supported: Email and HTTP.

HTTP notification configuration:

• APP_NOTIFIER=http
• APP_NOTIFIER_FROM=webhookd noreply@nunux.org
• APP_NOTIFIER_TO=hostmaster@nunux.org
• APP_HTTP_NOTIFIER_URL=http://requestb.in/v9b229v9

Note that the HTTP notification is compatible with Mailgun API.

SMTP notification configuration:

• APP_NOTIFIER=smtp
• APP_SMTP_NOTIFIER_HOST=localhost:25

The log file will be sent as an GZIP attachment.

You can restrict access to webhooks using HTTP basic authentication.

To activate basic authentication, you have to create a htpasswd file:

$ # create passwd file the user 'api'
$ htpasswd -B -c .htpasswd api

This command will ask for a password and store it in the htpawsswd file.

Please note that by default, the daemon will try to load the .htpasswd file.

But you can override this behavior by specifying the location of the file:

$ APP_PASSWD_FILE=/etc/webhookd/users.htpasswd
$ # or
$ webhookd -p /etc/webhookd/users.htpasswd

Once configured, you must call webhooks using basic authentication:

$ curl -u api:test -XPOST "http://localhost:8080/echo?msg=hello"