-
-If you don't have time to waste configuring, hosting, debugging and maintaining your webhook instance, we offer a __SaaS__ solution that has all of the capabilities webhook provides, plus a lot more, and all that packaged in a nice friendly web interface. If you are interested, find out more at [hookdoo website](https://www.hookdoo.com/?ref=github-webhook-readme). If you have any questions, you can contact us at info@hookdoo.com
-
-# What is webhook?
-[webhook](https://github.com/adnanh/webhook/) is a lightweight configurable tool written in Go, that allows you to easily create HTTP endpoints (hooks) on your server, which you can use to execute configured commands. You can also pass data from the HTTP request (such as headers, payload or query variables) to your commands. [webhook](https://github.com/adnanh/webhook/) also allows you to specify rules which have to be satisfied in order for the hook to be triggered.
-
-For example, if you're using Github or Bitbucket, you can use [webhook](https://github.com/adnanh/webhook/) to set up a hook that runs a redeploy script for your project on your staging server, whenever you push changes to the master branch of your project.
-
-If you use Mattermost or Slack, you can set up an "Outgoing webhook integration" or "Slash command" to run various commands on your server, which can then report back directly to you or your channels using the "Incoming webhook integrations", or the appropriate response body.
-
-[webhook](https://github.com/adnanh/webhook/) aims to do nothing more than it should do, and that is:
- 1. receive the request,
- 2. parse the headers, payload and query variables,
- 3. check if the specified rules for the hook are satisfied,
- 3. and finally, pass the specified arguments to the specified command via
- command line arguments or via environment variables.
-
-Everything else is the responsibility of the command's author.
-
-# Getting started
-## Installation
-### Building from source
-To get started, first make sure you've properly set up your [Golang](http://golang.org/doc/install) environment and then run the
-```bash
-$ go get github.com/adnanh/webhook
-```
-to get the latest version of the [webhook](https://github.com/adnanh/webhook/).
-
-### Using package manager
-#### Debian
-If you are using Debian linux ("stretch" or later), you can install webhook using `apt-get install webhook` which will install community packaged version (thanks [@freeekanayaka](https://github.com/freeekanayaka)) from https://packages.debian.org/sid/webhook
-
-### Download prebuilt binaries
-Prebuilt binaries for different architectures are available at [GitHub Releases](https://github.com/adnanh/webhook/releases).
-
-## Configuration
-Next step is to define some hooks you want [webhook](https://github.com/adnanh/webhook/) to serve. Begin by creating an empty file named `hooks.json`. This file will contain an array of hooks the [webhook](https://github.com/adnanh/webhook/) will serve. Check [Hook definition page](https://github.com/adnanh/webhook/wiki/Hook-Definition) to see the detailed description of what properties a hook can contain, and how to use them.
-
-Let's define a simple hook named `redeploy-webhook` that will run a redeploy script located in `/var/scripts/redeploy.sh`.
-
-Our `hooks.json` file will now look like this:
-```json
-[
- {
- "id": "redeploy-webhook",
- "execute-command": "/var/scripts/redeploy.sh",
- "command-working-directory": "/var/webhook"
- }
-]
-```
-
-You can now run [webhook](https://github.com/adnanh/webhook/) using
-```bash
-$ /path/to/webhook -hooks hooks.json -verbose
-```
-
-It will start up on default port 9000 and will provide you with one HTTP endpoint
-```http
-http://yourserver:9000/hooks/redeploy-webhook
-```
-
-Check [webhook parameters page](https://github.com/adnanh/webhook/wiki/Webhook-Parameters) to see how to override the ip, port and other settings such as hook hotreload, verbose output, etc, when starting the [webhook](https://github.com/adnanh/webhook/).
-
-By performing a simple HTTP GET or POST request to that endpoint, your specified redeploy script would be executed. Neat!
-
-However, hook defined like that could pose a security threat to your system, because anyone who knows your endpoint, can send a request and execute your command. To prevent that, you can use the `"trigger-rule"` property for your hook, to specify the exact circumstances under which the hook would be triggered. For example, you can use them to add a secret that you must supply as a parameter in order to successfully trigger the hook. Please check out the [Hook rules page](https://github.com/adnanh/webhook/wiki/Hook-Rules) for detailed list of available rules and their usage.
-
-## Using HTTPS
-[webhook](https://github.com/adnanh/webhook/) by default serves hooks using http. If you want [webhook](https://github.com/adnanh/webhook/) to serve secure content using https, you can use the `-secure` flag while starting [webhook](https://github.com/adnanh/webhook/). Files containing a certificate and matching private key for the server must be provided using the `-cert /path/to/cert.pem` and `-key /path/to/key.pem` flags. If the certificate is signed by a certificate authority, the cert file should be the concatenation of the server's certificate followed by the CA's certificate.
-
-## CORS Headers
-If you want to set CORS headers, you can use the `-header name=value` flag while starting [webhook](https://github.com/adnanh/webhook/) to set the appropriate CORS headers that will be returned with each response.
-
-## Interested in running webhook inside of a Docker container?
-You can use [almir/webhook](https://hub.docker.com/r/almir/webhook/) docker image, or create your own (please read [this discussion](https://github.com/adnanh/webhook/issues/63)).
-
-## Examples
-Check out [Hook examples page](https://github.com/adnanh/webhook/wiki/Hook-Examples) for more complex examples of hooks.
-
-### Guides featuring webhook
- - [Webhook & JIRA](https://sites.google.com/site/mrxpalmeiras/notes/jira-webhooks) by [@perfecto25](https://github.com/perfecto25)
- - [Trigger Ansible AWX job runs on SCM (e.g. git) commit](http://jpmens.net/2017/10/23/trigger-awx-job-runs-on-scm-commit/) by [@jpmens](http://mens.de/)
-
-## Community Contributions
-See the [webhook-contrib][wc] repository for a collections of tools and helpers related to [webhook][w] that have been contributed by the [webhook][w] community.
-
-## Need help?
-Check out [existing issues](https://github.com/adnanh/webhook/issues) to see if someone else also had the same problem, or [open a new one](https://github.com/adnanh/webhook/issues/new).
-
-# Support active development
-
-## Sponsors
-## 
-[BrowserStack](https://www.browserstack.com/?ref=webhook) is a cloud-based cross-browser testing tool that enables developers to test their websites across various browsers on different operating systems and mobile devices, without requiring users to install virtual machines, devices or emulators.
-
----
-
-Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
-
-
-
-
-
-
-
-
-
-
-
-
-## By contributing
-
-This project exists thanks to all the people who contribute. [Contribute!](CONTRIBUTING.md).
-
-
-## By giving money
-
- - [OpenCollective Backer](https://opencollective.com/webhook#backer)
- - [OpenCollective Sponsor](https://opencollective.com/webhook#sponsor)
- - [PayPal](https://paypal.me/hookdoo)
- - [Patreon](https://www.patreon.com/webhook)
- - [Faircode](https://faircode.io/product/webhook?utm_source=badge&utm_medium=badgelarge&utm_campaign=webhook)
- - [Flattr](https://flattr.com/submit/auto?user_id=adnanh&url=https%3A%2F%2Fwww.github.com%2Fadnanh%2Fwebhook)
-
----
-
-Thank you to all our backers!
-
-
-
-# License
-
-The MIT License (MIT)
-
-Copyright (c) 2015 Adnan Hajdarevic
+
+If you don't have time to waste configuring, hosting, debugging and maintaining your webhook instance, we offer a __SaaS__ solution that has all of the capabilities webhook provides, plus a lot more, and all that packaged in a nice friendly web interface. If you are interested, find out more at [hookdoo website](https://www.hookdoo.com/?ref=github-webhook-readme). If you have any questions, you can contact us at info@hookdoo.com
+
+# What is webhook?
+[webhook](https://github.com/adnanh/webhook/) is a lightweight configurable tool written in Go, that allows you to easily create HTTP endpoints (hooks) on your server, which you can use to execute configured commands. You can also pass data from the HTTP request (such as headers, payload or query variables) to your commands. [webhook](https://github.com/adnanh/webhook/) also allows you to specify rules which have to be satisfied in order for the hook to be triggered.
+
+For example, if you're using Github or Bitbucket, you can use [webhook](https://github.com/adnanh/webhook/) to set up a hook that runs a redeploy script for your project on your staging server, whenever you push changes to the master branch of your project.
+
+If you use Mattermost or Slack, you can set up an "Outgoing webhook integration" or "Slash command" to run various commands on your server, which can then report back directly to you or your channels using the "Incoming webhook integrations", or the appropriate response body.
+
+[webhook](https://github.com/adnanh/webhook/) aims to do nothing more than it should do, and that is:
+ 1. receive the request,
+ 2. parse the headers, payload and query variables,
+ 3. check if the specified rules for the hook are satisfied,
+ 3. and finally, pass the specified arguments to the specified command via
+ command line arguments or via environment variables.
+
+Everything else is the responsibility of the command's author.
+
+# Getting started
+## Installation
+### Building from source
+To get started, first make sure you've properly set up your [Golang](http://golang.org/doc/install) environment and then run the
+```bash
+$ go get github.com/adnanh/webhook
+```
+to get the latest version of the [webhook](https://github.com/adnanh/webhook/).
+
+### Using package manager
+#### Debian
+If you are using Debian linux ("stretch" or later), you can install webhook using `apt-get install webhook` which will install community packaged version (thanks [@freeekanayaka](https://github.com/freeekanayaka)) from https://packages.debian.org/sid/webhook
+
+### Download prebuilt binaries
+Prebuilt binaries for different architectures are available at [GitHub Releases](https://github.com/adnanh/webhook/releases).
+
+## Configuration
+Next step is to define some hooks you want [webhook](https://github.com/adnanh/webhook/) to serve. Begin by creating an empty file named `hooks.json`. This file will contain an array of hooks the [webhook](https://github.com/adnanh/webhook/) will serve. Check [Hook definition page](docs/Hook-Definition.md) to see the detailed description of what properties a hook can contain, and how to use them.
+
+Let's define a simple hook named `redeploy-webhook` that will run a redeploy script located in `/var/scripts/redeploy.sh`.
+
+Our `hooks.json` file will now look like this:
+```json
+[
+ {
+ "id": "redeploy-webhook",
+ "execute-command": "/var/scripts/redeploy.sh",
+ "command-working-directory": "/var/webhook"
+ }
+]
+```
+
+You can now run [webhook](https://github.com/adnanh/webhook/) using
+```bash
+$ /path/to/webhook -hooks hooks.json -verbose
+```
+
+It will start up on default port 9000 and will provide you with one HTTP endpoint
+```http
+http://yourserver:9000/hooks/redeploy-webhook
+```
+
+Check [webhook parameters page](docs/Webhook-Parameters.md) to see how to override the ip, port and other settings such as hook hotreload, verbose output, etc, when starting the [webhook](https://github.com/adnanh/webhook/).
+
+By performing a simple HTTP GET or POST request to that endpoint, your specified redeploy script would be executed. Neat!
+
+However, hook defined like that could pose a security threat to your system, because anyone who knows your endpoint, can send a request and execute your command. To prevent that, you can use the `"trigger-rule"` property for your hook, to specify the exact circumstances under which the hook would be triggered. For example, you can use them to add a secret that you must supply as a parameter in order to successfully trigger the hook. Please check out the [Hook rules page](docs/Hook-Rules.md) for detailed list of available rules and their usage.
+
+## Using HTTPS
+[webhook](https://github.com/adnanh/webhook/) by default serves hooks using http. If you want [webhook](https://github.com/adnanh/webhook/) to serve secure content using https, you can use the `-secure` flag while starting [webhook](https://github.com/adnanh/webhook/). Files containing a certificate and matching private key for the server must be provided using the `-cert /path/to/cert.pem` and `-key /path/to/key.pem` flags. If the certificate is signed by a certificate authority, the cert file should be the concatenation of the server's certificate followed by the CA's certificate.
+
+## CORS Headers
+If you want to set CORS headers, you can use the `-header name=value` flag while starting [webhook](https://github.com/adnanh/webhook/) to set the appropriate CORS headers that will be returned with each response.
+
+## Interested in running webhook inside of a Docker container?
+You can use [almir/webhook](https://hub.docker.com/r/almir/webhook/) docker image, or create your own (please read [this discussion](https://github.com/adnanh/webhook/issues/63)).
+
+## Examples
+Check out [Hook examples page](docs/Hook-Examples.md) for more complex examples of hooks.
+
+### Guides featuring webhook
+ - [Webhook & JIRA](https://sites.google.com/site/mrxpalmeiras/notes/jira-webhooks) by [@perfecto25](https://github.com/perfecto25)
+ - [Trigger Ansible AWX job runs on SCM (e.g. git) commit](http://jpmens.net/2017/10/23/trigger-awx-job-runs-on-scm-commit/) by [@jpmens](http://mens.de/)
+
+## Community Contributions
+See the [webhook-contrib][wc] repository for a collections of tools and helpers related to [webhook][w] that have been contributed by the [webhook][w] community.
+
+## Need help?
+Check out [existing issues](https://github.com/adnanh/webhook/issues) to see if someone else also had the same problem, or [open a new one](https://github.com/adnanh/webhook/issues/new).
+
+# Support active development
+
+## Sponsors
+##
+[BrowserStack](https://www.browserstack.com/?ref=webhook) is a cloud-based cross-browser testing tool that enables developers to test their websites across various browsers on different operating systems and mobile devices, without requiring users to install virtual machines, devices or emulators.
+
+---
+
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
+
+
+
+
+
+
+
+
+
+
+
+
+## By contributing
+
+This project exists thanks to all the people who contribute. [Contribute!](CONTRIBUTING.md).
+
+
+## By giving money
+
+ - [OpenCollective Backer](https://opencollective.com/webhook#backer)
+ - [OpenCollective Sponsor](https://opencollective.com/webhook#sponsor)
+ - [PayPal](https://paypal.me/hookdoo)
+ - [Patreon](https://www.patreon.com/webhook)
+ - [Faircode](https://faircode.io/product/webhook?utm_source=badge&utm_medium=badgelarge&utm_campaign=webhook)
+ - [Flattr](https://flattr.com/submit/auto?user_id=adnanh&url=https%3A%2F%2Fwww.github.com%2Fadnanh%2Fwebhook)
+
+---
+
+Thank you to all our backers!
+
+
+
+# License
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Adnan Hajdarevic
+[
+ {
+ "id": "test-file-webhook",
+ "execute-command": "/bin/ls",
+ "command-working-directory": "/tmp",
+ "pass-file-to-command":
+ [
+ {
+ "source": "payload",
+ "name": "binary",
+ "envname": "ENV_VARIABLE", // to use $ENV_VARIABLE in execute-command
+ // if not defined, $HOOK_BINARY will be provided
+ "base64decode": true, // defaults to false
+ }
+ ],
+ "include-command-output-in-response": true
+ }
+]
+
+
+## Sample client usage
+
+Store the following file as `testRequest.json`.
+
+
+{"binary":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA2lpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wUmlnaHRzPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvcmlnaHRzLyIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcFJpZ2h0czpNYXJrZWQ9IkZhbHNlIiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOjEzMTA4RDI0QzMxQjExRTBCMzYzRjY1QUQ1Njc4QzFBIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOjEzMTA4RDIzQzMxQjExRTBCMzYzRjY1QUQ1Njc4QzFBIiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIFBob3Rvc2hvcCBDUzMgV2luZG93cyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ1dWlkOkFDMUYyRTgzMzI0QURGMTFBQUI4QzUzOTBEODVCNUIzIiBzdFJlZjpkb2N1bWVudElEPSJ1dWlkOkM5RDM0OTY2NEEzQ0REMTFCMDhBQkJCQ0ZGMTcyMTU2Ii8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+IBFgEwAAAmJJREFUeNqkk89rE1EQx2d/NNq0xcYYayPYJDWC9ODBsKIgAREjBmvEg2cvHnr05KHQ9iB49SL+/BMEfxBQKHgwCEbTNNIYaqgaoanFJi+rcXezye4689jYkIMIDnx47837zrx583YFx3Hgf0xA6/dJyAkkgUy4vgryAnmNWH9L4EVmotFoKplMHgoGg6PkrFarjXQ6/bFcLj/G5W1E+3NaX4KZeDx+dX5+7kg4HBlmrC6JoiDFYrGhROLM/mp1Y6JSqdCd3/SW0GUqEAjkl5ZyHTSHKBQKnO6a9khD2m5cr91IJBJ1VVWdiM/n6LruNJtNDs3JR3ukIW03SHTHi8iVsbG9I51OG1bW16HVasHQZopDc/JZVgdIQ1o3BmTkEnJXURS/KIpgGAYPkCQJPi0u8uzDKQN0XQPbtgE1MmrHs9nsfSqAEjxCNtHxZHLy4G4smUQgyzL4LzOegDGGp1ucVqsNqKVrpJCM7F4hg6iaZvhqtZrg8XjA4xnAU3XeKLqWaRImoIZeQXVjQO5pYp4xNVirsR1erxer2O4yfa227WCwhtWoJmn7m0h270NxmemFW4706zMm8GCgxBGEASCfhnukIW03iFdQnOPz0LNKp3362JqQzSw4u2LXBe+Bs3xD+/oc1NxN55RiC9fOme0LEQiRf2rBzaKEeJJ37ZWTVunBeGN2WmQjg/DeLTVP89nzAive2dMwlo9bpFVC2xWMZr+A720FVn88fAUb3wDMOjyN7YNc6TvUSHQ4AH6TOUdLL7em68UtWPsJqxgTpgeiLu1EBt1R+Me/mF7CQPTfAgwAGxY2vOTrR3oAAAAASUVORK5CYII="}
+
+
+use then the curl tool to execute a request to the webhook.
+
++#!/bin/bash +curl -H "Content-Type:application/json" -X POST -d @testRequest.json \ +http://localhost:9000/hooks/test-file-webhook ++ +or in a single line, using https://github.com/jpmens/jo to generate the JSON code +
+jo binary=%filename.zip | curl -H "Content-Type:application/json" -X POST -d @- \ +http://localhost:9000/hooks/test-file-webhook +diff --git a/docs/Hook-Rules.md b/docs/Hook-Rules.md new file mode 100644 index 0000000..32d35d3 --- /dev/null +++ b/docs/Hook-Rules.md @@ -0,0 +1,201 @@ +# Hook rules + +## And +*And rule* will evaluate to _true_, if and only if all of the sub rules evaluate to _true_. +```json +{ +"and": + [ + { + "match": + { + "type": "value", + "value": "refs/heads/master", + "parameter": + { + "source": "payload", + "name": "ref" + } + } + }, + { + "match": + { + "type": "regex", + "regex": ".*", + "parameter": + { + "source": "payload", + "name": "repository.owner.name" + } + } + } + ] +} +``` +## Or +*Or rule* will evaluate to _true_, if any of the sub rules evaluate to _true_. +```json +{ +"or": + [ + { + "match": + { + "type": "value", + "value": "refs/heads/master", + "parameter": + { + "source": "payload", + "name": "ref" + } + } + }, + { + "match": + { + "type": "value", + "value": "refs/heads/development", + "parameter": + { + "source": "payload", + "name": "ref" + } + } + } + ] +} +``` +## Not +*Not rule* will evaluate to _true_, if and only if the sub rule evaluates to _false_. +```json +{ +"not": + { + "match": + { + "type": "value", + "value": "refs/heads/development", + "parameter": + { + "source": "payload", + "name": "ref" + } + } + } +} +``` +## Multi-level +```json +{ + "and": [ + { + "match": { + "parameter": { + "source": "header", + "name": "X-Hub-Signature" + }, + "type": "payload-hash-sha1", + "secret": "mysecret" + } + }, + { + "or": [ + { + "match": + { + "parameter": + { + "source": "payload", + "name": "ref" + }, + "type": "value", + "value": "refs/heads/master" + } + }, + { + "match": + { + "parameter": + { + "source": "header", + "name": "X-GitHub-Event" + }, + "type": "value", + "value": "ping" + } + } + ] + } + ] +} +``` +## Match +*Match rule* will evaluate to _true_, if and only if the referenced value in the `parameter` field satisfies the `type`-specific rule. + +*Please note:* Due to technical reasons, _number_ and _boolean_ values in the _match rule_ must be wrapped around with a pair of quotes. + +There are three different match rules: + +### 1. Match value +```json +{ + "match": + { + "type": "value", + "value": "refs/heads/development", + "parameter": + { + "source": "payload", + "name": "ref" + } + } +} +``` + +### 2. Match regex +For the regex syntax, check out