A webhook server that schedules commands on request. Uses Pueue as executor backend.
MIT License
This little helper serves a simple purpose: Execute commands on your server on incoming http requests. It has been designed for continuous integration and supports Github's webhooks out of the box.
Webhook-Server works in conjunction with Pueue, which allows easy output inspection, loggin and debugging of your webhook calls.
Example applications:
Take a look at the example config file webhook_server.yml.
Manual installation:
git clone https://github.com/nukesor/pueue-webhook-server
cd pueue-webhook-server
cargo install --locked --path .
Your $CARGO_HOME/bin
folder should be in your $PATH.
Webhook-Server is configured via files in this order:
/etc/webhook_server.yml
~/.config/webhook_server.yml
./webhook_server.yml
Config values of higher hierarchy config files are overwritten by lower hierarchy config files. E.g. a value in /etc/webhook_server.yml
can be overwritten by ~/.config/webhook_server.yml
.
domain (127.0.0.1)
The domain the server should listen onport (8000)
The port the server should listen onsecret (null)
A secret for authentication via payload signature verification. Check the Building a request
section for more information on signature headers. Can be, for instance, be created with pwgen 25 1
ssl_private_key (null)
Path to SSL private key. The server will use it's own ssl certificate. Recommended, if you aren't using a proxy webserver, that already uses SSL. Using any kind of SSL is highly recommended, especially if you publicly expose your endpoint.ssl_cert_chain (null)
Path to SSL cert. Also required for SSL setup.basic_auth_user (null)
Your user if you want to do basic auth. Check the Building a request
section for more information on basic_auth headersbasic_auth_password (null)
Your password if you want to do basic auth.basic_auth_and_secret (false)
By default it's only required to authenticate via BasicAuth OR signature authentication. If you want to be super safe, set this to true to require both.pueue_port (6924)
Set this to the port your local pueue instance listens on.pueue_unix_socket (null)
In case you're using unix sockets, set this to your Pueue's socket path and pueue_port
to null
.pueue_directory
The working directory of Pueue, can be found in Pueue's configuration file.webhooks
A list of webhooks. The whole thing looks pretty much like this:webhooks:
-
name: 'ls'
command: '/bin/ls {{param1}} {{param2}}'
cwd: '/home/user'
pueue_group: 'webhook'
Webhook config values
name
The name of the webhook, also the endpoint that's used to trigger the webhooks. E.g. localhost:8000/ls
.command
The command thats actually used. If you want to dynamically build the command, you can use templating parameters like {{name_of_parameter}}
.cwd
The current working directory the command should be executed from.pueue_group
Which pueue group should be used for this webhook.There are some template files for your setup in the misc folder of the repository. These include:
If you got anything else that might be useful to others, feel free to create a PR.
Go to your project's settings tab and select webhooks. Create a new one and set these options:
You can click on the Recent Deliveries
to redeliver any sent webhook, in case you want to debug your setup.
Webhook server accepts JSON POST requests and simple GET requests.
This is an example POST request issued with httpie
and a secret of 72558847d57c22a2f19d711537cdc446
and test:testtest
basic auth credentials:
echo -n '{"parameters":{"param1":"-al","param2":"/tmp"}}' | http POST localhost:8000/ls \
Signature:'sha1=d762407ca7fb309dfbeb73c080caf6394751f0a4' \
Authorization:'Basic dGVzdDp0ZXN0dGVzdA=='
If you don't need templating, you can send a simple GET request:
http GET localhost:8000/ls Authorization:'Basic dGVzdDp0ZXN0dGVzdA=='
Payload:
The payload is a simple JSON object, with a single entry parameters
.
This object contains all parameters necessary for rendering the template.
If no templating is needed, you can provide an empty object as payload or simply call the route via GET
.
For instance, the payload for the command '/bin/ls {{param1}} {{param2}}'
could look like this:
{
"parameters": {
"param1": "-al",
"param2": "/tmp"
}
}
This would result in the execution of ls -al /tmp
by the server.
Headers:
Authorization
: If basic_auth_username
and basic_auth_password
is specified, this should be the standard Basic
base64 encoded authorization header. Basic Auth guide
Signature:
If you specify a secret, the content of the signature is the HMAC of the json payload with the UTF8-encoded secret as key.hmac.new(key, payload, hashlib.sha1)
OpenSSL::HMAC.hexdigest("SHA1", key, payload)
X-Hub-Signature
: If there is no Signature
, this header will be used for the signature check (to support Github's webhooks).Code injection: When compiling dynamic commands with templating, you make yourself vulnerable to code injection, since the compiled commands are executed by the system shell. If you plan on using templating and publicly exposing your service, please use some kind of authentication.
SSL: Especially when using Basic Auth or templating it's highly recommended to use SSL encryption. This can be either done by your proxy web server (nginx, apache, caddy) or directly in the application. Otherwise your credentials or your template payload could leak to anybody listening.
An example cert and key can be created like this openssl req -nodes -new -x509 -keyout test.pem -out test.pem
.
If you need a password input for the private key, please create an issue or PR (much appreciated).