All Projects → ncarlier → Webhookd

ncarlier / Webhookd

Licence: mit
A very simple webhook server launching shell scripts.

Programming Languages

go
31211 projects - #10 most used programming language
bash
514 projects

Projects that are alternatives of or similar to Webhookd

Gocd
Main repository for GoCD - Continuous Delivery server
Stars: ✭ 6,314 (+2425.6%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Rok8s Scripts
Opinionated scripts for managing application deployment lifecycle in Kubernetes
Stars: ✭ 248 (-0.8%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Cimonitor
Displays CI statuses on a dashboard and triggers fun modules representing the status!
Stars: ✭ 34 (-86.4%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Abstruse
Abstruse is a free and open-source CI/CD platform that tests your models and code.
Stars: ✭ 704 (+181.6%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
www.go.cd
Github pages repo
Stars: ✭ 39 (-84.4%)
Mutual labels:  continuous-integration, ci, cd, continuous-deployment
flagsmith-nodejs-client
Flagsmith Node JS Client. Flagsmith lets you manage features flags across web, mobile and server side applications. Get builds out faster. Control who has access to new features.
Stars: ✭ 13 (-94.8%)
Mutual labels:  continuous-integration, ci, cd, continuous-deployment
Orkestra
Functional DevOps with Scala and Kubernetes
Stars: ✭ 102 (-59.2%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Nevergreen
🐤 A build monitor with attitude
Stars: ✭ 170 (-32%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Rocket
Automated software delivery as fast and easy as possible 🚀
Stars: ✭ 217 (-13.2%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
setup-scheme
Github Actions CI / CD setup for Scheme
Stars: ✭ 13 (-94.8%)
Mutual labels:  continuous-integration, ci, cd, continuous-deployment
Pipelines
Build pipelines for automation, deployment, testing...
Stars: ✭ 105 (-58%)
Mutual labels:  ci, continuous-integration, continuous-deployment, cd
Haiku
🚀 Instant Heroku deploys from GitHub branches
Stars: ✭ 17 (-93.2%)
Mutual labels:  ci, continuous-integration, continuous-deployment
Simpleci
Simple docker-based continuous integration system
Stars: ✭ 61 (-75.6%)
Mutual labels:  ci, continuous-integration, continuous-deployment
Wflow
🐆 EXPERIMENTAL -- Runs GitHub Actions workflows locally (local) -- Don't run your YAML like a 🐪
Stars: ✭ 187 (-25.2%)
Mutual labels:  ci, continuous-integration, continuous-deployment
Lambdacd
a library to define a continuous delivery pipeline in code
Stars: ✭ 655 (+162%)
Mutual labels:  ci, continuous-integration, cd
Jmeter Elasticsearch Backend Listener
JMeter plugin that lets you send sample results to an ElasticSearch engine to enable live monitoring of load tests.
Stars: ✭ 72 (-71.2%)
Mutual labels:  ci, continuous-integration, cd
Leeroyci
Leeroy is a self hosted, continuous integration and build service
Stars: ✭ 84 (-66.4%)
Mutual labels:  ci, continuous-integration, continuous-deployment
Flint
Fast and configurable filesystem (file and directory names) linter
Stars: ✭ 115 (-54%)
Mutual labels:  ci, continuous-integration, cd
Lastbackend
System for containerized apps management. From build to scaling.
Stars: ✭ 1,536 (+514.4%)
Mutual labels:  ci, continuous-integration, cd
Gitlab Ci Pipeline Php
☕️ Docker images for test PHP applications with Gitlab CI (or any other CI platform!)
Stars: ✭ 451 (+80.4%)
Mutual labels:  ci, continuous-integration, cd

webhookd

Build Status Go Report Card Docker pulls Donate

A very simple webhook server to launch shell scripts.

Logo

At a glance

Demo

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 \
  -v ${PWD}/scripts:/var/opt/webhookd/scripts \
  -p 8080:8080 \
  ncarlier/webhookd \
  webhookd --scripts=/var/opt/webhookd/scripts

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

Or use APT:

Finally, it is possible to install Webhookd using the Debian packaging system through this custom repository.

Note that custom configuration variables can be set into /etc/webhookd.env file. Sytemd service is already set and enable, you just have to start it with systemctl start webhookd.

Configuration

Webhookd can be configured by using command line parameters or by setting environment variables.

Type webhookd -h to display all parameters and related environment variables.

All configuration variables are described in etc/default/webhookd.env file.

Usage

Directory structure

Webhooks are simple scripts within a directory structure.

By default inside the ./scripts directory. You can override the default using the WHD_SCRIPTS environment variable or -script parameter.

Example:

/scripts
|--> /github
  |--> /build.sh
  |--> /deploy.sh
|--> /push.js
|--> /echo.sh
|--> ...

Note that Webhookd is able to run any type of file in this directory as long as the file is executable. For example, you can execute a Node.js file if you give execution rights to the file and add the appropriate #! header (in this case: #!/usr/bin/env node).

You can find sample scripts in the example folder. In particular, examples of integration with Gitlab and Github.

Webhook URL

The directory structure define the webhook URL.

You can omit the script extension. If you do, webhookd will search for a .sh file. If the script exists, the output the will be streamed to the HTTP response.

The streaming technology depends on the HTTP method used. With POST the response will be chunked. With GET the response will use Server-sent events.

Example:

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

#!/bin/bash

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

Output using POST (Chunked transfer encoding):

$ curl -v -XPOST http://localhost:8080/foo/bar
< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8
< Transfer-Encoding: chunked
< X-Hook-Id: 7
foo foo foo
bar bar bar

Output using GET (Server-sent events):

$ curl -v -XGET http://localhost:8080/foo/bar
< HTTP/1.1 200 OK
< Content-Type: text/event-stream
< Transfer-Encoding: chunked
< X-Hook-Id: 8
data: foo foo foo

data: bar bar bar

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 become content_type.

  • When using POST, 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
Query parameter: foo=bar
Header parameter: user-agent=curl/7.52.1
Script parameter: {"foo": "bar"}

Webhook timeout configuration

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

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

Example:

$ curl -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 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 output of the script is collected and stored into a log file (configured by the WHD_LOG_DIR environment variable).

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

Notifications configuration can be done as follow:

$ export WHD_NOTIFICATION_URI=http://requestb.in/v9b229v9
$ # or
$ webhookd --notification-uri=http://requestb.in/v9b229v9

Note that only the output of the script prefixed by "notify:" is sent to the notification channel. If the output does not contain a prefixed line, no notification will be sent.

Example:

#!/bin/bash

echo "notify: Hello World" # Will be notified
echo "Goodbye"             # Will not be notified

You can override the notification prefix by adding prefix as a query parameter to the configuration URL.

Example: http://requestb.in/v9b229v9?prefix="foo:"

HTTP notification

Configuration URI: http://example.org

Options (using query parameters):

  • prefix: Prefix to filter output log

The following JSON payload is POST to the target URL:

{
  "id": "42",
  "name": "echo",
  "text": "foo\nbar...\n",
  "error": "Error cause... if present",
}

Note that because the payload have a text attribute, you can use a Mattermost webhook endpoint.

Email notification

Configuration URI: mailto:[email protected]

Options (using query parameters):

  • prefix: Prefix to filter output log
  • smtp: SMTP host to use (by default: localhost:25)
  • username: SMTP username (not set by default)
  • password: SMTP password (not set by default)
  • conn: SMTP connection type (tls, tls-insecure or by default: plain)
  • from: Sender email (by default: [email protected])

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:

$ export WHD_PASSWD_FILE=/etc/webhookd/users.htpasswd
$ # or
$ webhookd --passwd-file /etc/webhookd/users.htpasswd

Once configured, you must call webhooks using basic authentication:

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

Signature

You can ensure message integrity (and authenticity) with HTTP Signatures.

To activate HTTP signature verification, you have to configure the trust store:

$ export WHD_TRUST_STORE_FILE=/etc/webhookd/pubkey.pem
$ # or
$ webhookd --trust-store-file /etc/webhookd/pubkey.pem

Public key is stored in PEM format.

Once configured, you must call webhooks using a valid HTTP signature:

$ curl -X POST \
  -H 'Date: <req-date>' \
  -H 'Signature: keyId=<key-id>,algorithm="rsa-sha256",headers="(request-target) date",signature=<signature-string>' \
  -H 'Accept: application/json' \
  "http://localhost:8080/echo?msg=hello"

You can find a small HTTP client in the "tooling" directory that is capable of forging HTTP signatures.

TLS

You can activate TLS to secure communications:

$ export WHD_TLS=true
$ # or
$ webhookd --tls

By default webhookd is expecting a certificate and key file (./server.pem and ./server.key). You can provide your own certificate and key with -tls-cert-file and -tls-key-file.

Webhookd also support ACME protocol. You can activate ACME by setting a fully qualified domain name:

$ export WHD_TLS=true
$ export WHD_TLS_DOMAIN=hook.example.com
$ # or
$ webhookd --tls --tls-domain=hook.example.com

Note: On *nix, if you want to listen on ports 80 and 443, don't forget to use setcap to privilege the binary:

sudo setcap CAP_NET_BIND_SERVICE+ep webhookd

License

The MIT License (MIT)

See LICENSE to see the full text.


Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].