makefiles@c249aaa5d4 | ||
pkg | ||
scripts | ||
tests | ||
.dockerignore | ||
.env | ||
.gitignore | ||
.gitmodules | ||
.travis.yml | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
docker-entrypoint.sh | ||
Dockerfile | ||
go.mod | ||
go.sum | ||
install.sh | ||
LICENSE | ||
main.go | ||
Makefile | ||
README.md | ||
version.go | ||
webhookd.svg |
webhookd
A very simple webhook server to launch shell scripts.
Installation
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.
Configuration
You can configure the daemon by:
Setting environment variables:
Variable | Default | Description |
---|---|---|
APP_LISTEN_ADDR |
:8080 |
HTTP service address |
APP_PASSWD_FILE |
.htpasswd |
Password file for HTTP basic authentication |
APP_NB_WORKERS |
2 |
The number of workers to start |
APP_HOOK_TIMEOUT |
10 |
Hook maximum delay before timeout (in second) |
APP_SCRIPTS_DIR |
./scripts |
Scripts directory |
APP_SCRIPTS_GIT_URL |
none | GIT repository that contains scripts (Note: this is only used by the Docker image or by using the Docker entrypoint script) |
APP_SCRIPTS_GIT_KEY |
none | GIT SSH private key used to clone the repository (Note: this is only used by the Docker image or by using the Docker entrypoint script) |
APP_LOG_DIR |
/tmp (OS temp dir) |
Directory to store execution logs |
APP_NOTIFIER |
none | Post script notification (http or smtp ) |
APP_NOTIFIER_FROM |
none | Sender of the notification |
APP_NOTIFIER_TO |
none | Recipient of the notification |
APP_HTTP_NOTIFIER_URL |
none | URL of the HTTP notifier |
APP_SMTP_NOTIFIER_HOST |
none | Hostname of the SMTP relay |
APP_DEBUG |
false |
Output debug logs |
Using command parameters:
Parameter | Default | Description |
---|---|---|
-l <address> or --listen <address> |
:8080 |
HTTP service address |
-p or --passwd <htpasswd file> |
.htpasswd |
Password file for HTTP basic authentication |
-d or --debug |
false | Output debug logs |
--nb-workers <workers> |
2 |
The number of workers to start |
--scripts <dir> |
./scripts |
Scripts directory |
--timeout <timeout> |
10 |
Hook maximum delay before timeout (in second) |
Usage
Directory structure
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
|--> ...
Webhook URL
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:8080/foo/bar
data: foo foo foo
data: bar bar bar
data: done
Webhook parameters
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 becomecontent_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:8080/echo?foo=bar
data: Query parameter: foo=bar
data: Header parameter: user-agent=curl/7.52.1
data: Script parameter: {"foo": "bar"}
data: done
Webhook timeout configuration
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:8080/echo?foo=bar
Webhook logs
As mentioned above, web hook logs are stream in real time during the call.
However, you can retrieve the logs of a previous call by using the hook ID: http://localhost:8080/<NAME>/<ID>
The hook ID is returned as an HTTP header with the Webhook response: X-Hook-ID
Example:
$ # Call webhook
$ curl -v -XPOST http://localhost:8080/echo?foo=bar
...
< HTTP/1.1 200 OK
< Content-Type: text/event-stream
< X-Hook-Id: 2
...
$ # Retrieve logs afterwards
$ curl http://localhost:8080/echo/2
Post hook notifications
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
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.
Email notification
SMTP notification configuration:
- APP_NOTIFIER=smtp
- APP_SMTP_NOTIFIER_HOST=localhost:25
The log file will be sent as an GZIP attachment.
Authentication
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"