Merge branch 'development'

.github/workflows/build.yml

@@ -0,0 +1,23 @@
+name: build
+on: [push, pull_request]
+jobs:
+  build:
+    strategy:
+      matrix:
+        go-version: [1.14.x, 1.15.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-go@v2
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Build
+        run: go build -v
+
+      - name: Test
+        run: go test -v ./...

.travis.yml

@@ -1,7 +1,7 @@
 language: go
 
 go:
-  - 1.13.x
+  - 1.14.x
   - master
 
 os:

README.md

@@ -1,4 +1,4 @@
-# What is webhook?
+# What is webhook? ![build-status][badge]
 
  <img src="https://github.com/adnanh/webhook/raw/development/docs/logo/logo-128x128.png" alt="Webhook" align="left" />
 
@@ -29,7 +29,7 @@ If you don't have time to waste configuring, hosting, debugging and maintaining
 # Getting started
 ## Installation
 ### Building from source
-To get started, first make sure you've properly set up your [Go](http://golang.org/doc/install) 1.12 or newer environment and then run
+To get started, first make sure you've properly set up your [Go](http://golang.org/doc/install) 1.14 or newer environment and then run
 ```bash
 $ go build github.com/adnanh/webhook
 ```
@@ -49,7 +49,9 @@ If you are using Debian linux ("stretch" or later), you can install webhook usin
 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][w] to serve. Begin by creating an empty file named `hooks.json`. This file will contain an array of hooks the [webhook][w] 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.
+Next step is to define some hooks you want [webhook][w] to serve.
+[webhook][w] supports JSON or YAML configuration files, but we'll focus primarily on JSON in the following example.
+Begin by creating an empty file named `hooks.json`. This file will contain an array of hooks the [webhook][w] 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`. Make sure that your bash script has `#!/bin/sh` shebang on top.
 
@@ -64,6 +66,13 @@ Our `hooks.json` file will now look like this:
 ]
 ```
 
+**NOTE:** If you prefer YAML, the equivalent `hooks.yaml` file would be:
+```yaml
+- id: redeploy-webhook
+  execute-command: "/var/scripts/redeploy.sh"
+  command-working-directory: "/var/webhook"
+```
+
 You can now run [webhook][w] using
 ```bash
 $ /path/to/webhook -hooks hooks.json -verbose
@@ -93,7 +102,7 @@ All files are ignored unless they match one of the following criteria:
 In either case, the given file part will be parsed as JSON and added to the `payload` map.
 
 ## Templates
-[webhook][w] can parse the `hooks.json` input file as a Go template when given the `-template` [CLI parameter](docs/Webhook-Parameters.md). See the [Templates page](docs/Templates.md) for more details on template usage.
+[webhook][w] can parse the hooks configuration file as a Go template when given the `-template` [CLI parameter](docs/Webhook-Parameters.md). See the [Templates page](docs/Templates.md) for more details on template usage.
 
 ## Using HTTPS
 [webhook][w] by default serves hooks using http. If you want [webhook][w] to serve secure content using https, you can use the `-secure` flag while starting [webhook][w]. 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.
@@ -206,3 +215,4 @@ THE SOFTWARE.
 
 [w]: https://github.com/adnanh/webhook
 [wc]: https://github.com/adnanh/webhook-contrib
+[badge]: https://github.com/adnanh/webhook/workflows/build/badge.svg

docs/Hook-Definition.md

@@ -1,5 +1,6 @@
 # Hook definition
-Hooks are defined as JSON objects. Please note that in order to be considered valid, a hook object must contain the `id` and `execute-command` properties. All other properties are considered optional.
+
+Hooks are defined as objects in the JSON or YAML hooks configuration file. Please note that in order to be considered valid, a hook object must contain the `id` and `execute-command` properties. All other properties are considered optional.
 
 ## Properties (keys)
 
@@ -21,6 +22,7 @@ Hooks are defined as JSON objects. Please note that in order to be considered va
 * `pass-file-to-command` - specifies a list of entries that will be serialized as a file. Incoming [data](Referencing-Request-Values.md) will be serialized in a request-temporary-file (otherwise parallel calls of the hook would lead to concurrent overwritings of the file). The filename to be addressed within the subsequent script is provided via an environment variable. Use `envname` to specify the name of the environment variable. If `envname` is not provided `HOOK_` and the name used to reference the request value are used. Defining `command-working-directory` will store the file relative to this location, if not provided, the systems temporary file directory will be used.  If `base64decode` is true, the incoming binary data will be base 64 decoded prior to storing it into the file. By default the corresponding file will be removed after the webhook exited.
  * `trigger-rule` - specifies the rule that will be evaluated in order to determine should the hook be triggered. Check [Hook rules page](Hook-Rules.md) to see the list of valid rules and their usage
  * `trigger-rule-mismatch-http-response-code` - specifies the HTTP status code to be returned when the trigger rule is not satisfied
+ * `trigger-signature-soft-failures` - allow signature validation failures within Or rules; by default, signature failures are treated as errors.
 
 ## Examples
 Check out [Hook examples page](Hook-Examples.md) for more complex examples of hooks.

docs/Hook-Examples.md

@@ -1,5 +1,26 @@
-# Hook examples
-This page is still work in progress. Feel free to contribute!
+# Hook Examples
+
+Hooks are defined in a hooks configuration file in either JSON or YAML format,
+although the examples on this page all use the JSON format.
+
+🌱 This page is still a work in progress. Feel free to contribute!
+
+### Table of Contents
+
+* [Incoming Github webhook](#incoming-github-webhook)
+* [Incoming Bitbucket webhook](#incoming-bitbucket-webhook)
+* [Incoming Gitlab webhook](#incoming-gitlab-webhook)
+* [Incoming Gogs webhook](#incoming-gogs-webhook)
+* [Incoming Gitea webhook](#incoming-gitea-webhook)
+* [Slack slash command](#slack-slash-command)
+* [A simple webhook with a secret key in GET query](#a-simple-webhook-with-a-secret-key-in-get-query)
+* [JIRA Webhooks](#jira-webhooks)
+* [Pass File-to-command sample](#pass-file-to-command-sample)
+* [Incoming Scalr Webhook](#incoming-scalr-webhook)
+* [Travis CI webhook](#travis-ci-webhook)
+* [XML Payload](#xml-payload)
+* [Multipart Form Data](#multipart-form-data)
+* [Pass string arguments to command](#pass-string-arguments-to-command)
 
 ## Incoming Github webhook
 ```json
@@ -30,7 +51,7 @@ This page is still work in progress. Feel free to contribute!
         {
           "match":
           {
-            "type": "payload-hash-sha1",
+            "type": "payload-hmac-sha1",
             "secret": "mysecret",
             "parameter":
             {
@@ -150,7 +171,7 @@ Values in the request body can be accessed in the command or to the match rule b
         {
           "match":
           {
-            "type": "payload-hash-sha256",
+            "type": "payload-hmac-sha256",
             "secret": "mysecret",
             "parameter":
             {
@@ -425,6 +446,57 @@ Travis sends webhooks as `payload=<JSON_STRING>`, so the payload needs to be par
 ]
 ```
 
+## JSON Array Payload
+
+If the JSON payload is an array instead of an object, `webhook` will process the payload and place it into a "root" object.
+Therefore, references to payload values must begin with `root.`.
+
+For example, given the following payload (taken from the Sendgrid Event Webhook documentation):
+```json
+[
+  {
+    "email": "[email protected]",
+    "timestamp": 1513299569,
+    "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
+    "event": "processed",
+    "category": "cat facts",
+    "sg_event_id": "sg_event_id",
+    "sg_message_id": "sg_message_id"
+  },
+  {
+    "email": "[email protected]",
+    "timestamp": 1513299569,
+    "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
+    "event": "deferred",
+    "category": "cat facts",
+    "sg_event_id": "sg_event_id",
+    "sg_message_id": "sg_message_id",
+    "response": "400 try again later",
+    "attempt": "5"
+  }
+]
+```
+
+A reference to the second item in the array would look like this:
+```json
+[
+  {
+    "id": "sendgrid",
+    "execute-command": "{{ .Hookecho }}",
+    "trigger-rule": {
+      "match": {
+        "type": "value",
+        "parameter": {
+          "source": "payload",
+          "name": "root.1.event"
+        },
+        "value": "deferred"
+      }
+    }
+  }
+]
+```
+
 ## XML Payload
 
 Given the following payload:
@@ -518,3 +590,34 @@ Content-Disposition: form-data; name="thumb"; filename="thumb.jpg"
 ```
 
 We key off of the `name` attribute in the `Content-Disposition` value.
+
+## Pass string arguments to command
+
+To pass simple string arguments to a command, use the `string` parameter source.
+The following example will pass two static string parameters ("-e 123123") to the
+`execute-command` before appending the `pusher.email` value from the payload:
+
+```json
+[
+  {
+    "id": "webhook",
+    "execute-command": "/home/adnan/redeploy-go-webhook.sh",
+    "command-working-directory": "/home/adnan/go",
+    "pass-arguments-to-command":
+    [
+      {
+        "source": "string",
+        "name": "-e"
+      },
+      {
+        "source": "string",
+        "name": "123123"
+      },
+      {
+        "source": "payload",
+        "name": "pusher.email"
+      }
+    ]
+  }
+]
+```

docs/Hook-Rules.md

@@ -1,5 +1,20 @@
 # Hook rules
 
+### Table of Contents
+
+* [And](#and)
+* [Or](#or)
+* [Not](#not)
+* [Multi-level](#multi-level)
+* [Match](#match)
+  * [Match value](#match-value)
+  * [Match regex](#match-regex)
+  * [Match payload-hmac-sha1](#match-payload-hmac-sha1)
+  * [Match payload-hmac-sha256](#match-payload-hmac-sha256)
+  * [Match payload-hmac-sha512](#match-payload-hmac-sha512)
+  * [Match Whitelisted IP range](#match-whitelisted-ip-range)
+  * [Match scalr-signature](#match-scalr-signature)
+
 ## And
 *And rule* will evaluate to _true_, if and only if all of the sub rules evaluate to _true_.
 ```json
@@ -95,7 +110,7 @@
                 "source": "header",
                 "name": "X-Hub-Signature"
             },
-            "type": "payload-hash-sha1",
+            "type": "payload-hmac-sha1",
             "secret": "mysecret"
         }
     },
@@ -135,9 +150,7 @@
 
 *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
+### Match value
 ```json
 {
   "match":
@@ -153,7 +166,7 @@ There are three different match rules:
 }
 ```
 
-### 2. Match regex
+### Match regex
 For the regex syntax, check out <http://golang.org/pkg/regexp/syntax/>
 ```json
 {
@@ -170,12 +183,13 @@ For the regex syntax, check out <http://golang.org/pkg/regexp/syntax/>
 }
 ```
 
-### 3. Match payload-hash-sha1
+### Match payload-hmac-sha1
+Validate the HMAC of the payload using the SHA1 hash and the given *secret*.
 ```json
 {
   "match":
   {
-    "type": "payload-hash-sha1",
+    "type": "payload-hmac-sha1",
     "secret": "yoursecret",
     "parameter":
     {
@@ -193,12 +207,13 @@ will be tried unless a match is found. For example:
 X-Hub-Signature: sha1=the-first-signature,sha1=the-second-signature
 ```
 
-### 4. Match payload-hash-sha256
+### Match payload-hmac-sha256
+Validate the HMAC of the payload using the SHA256 hash and the given *secret*.
 ```json
 {
   "match":
   {
-    "type": "payload-hash-sha256",
+    "type": "payload-hmac-sha256",
     "secret": "yoursecret",
     "parameter":
     {
@@ -216,12 +231,13 @@ will be tried unless a match is found. For example:
 X-Hub-Signature: sha256=the-first-signature,sha256=the-second-signature
 ```
 
-### 5. Match payload-hash-sha512
+### Match payload-hmac-sha512
+Validate the HMAC of the payload using the SHA512 hash and the given *secret*.
 ```json
 {
   "match":
   {
-    "type": "payload-hash-sha512",
+    "type": "payload-hmac-sha512",
     "secret": "yoursecret",
     "parameter":
     {
@@ -239,7 +255,7 @@ will be tried unless a match is found. For example:
 X-Hub-Signature: sha512=the-first-signature,sha512=the-second-signature
 ```
 
-### 6. Match Whitelisted IP range
+### Match Whitelisted IP range
 
 The IP can be IPv4- or IPv6-formatted, using [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_blocks).  To match a single IP address only, use `/32`.
 
@@ -253,7 +269,7 @@ The IP can be IPv4- or IPv6-formatted, using [CIDR notation](https://en.wikipedi
 }
 ```
 
-### 7. Match scalr-signature
+### Match scalr-signature
 
 The trigger rule checks the scalr signature and also checks that the request was signed less than 5 minutes before it was received. 
 A unqiue signing key is generated for each webhook endpoint URL you register in Scalr.
@@ -267,4 +283,4 @@ Given the time check make sure that NTP is enabled on both your Scalr and webhoo
     "secret": "Scalr-provided signing key"
   }
 }
-```
+```