Merge branch 'development' into feature/context-provider-command

docs/Hook-Definition.md

@@ -10,6 +10,7 @@ Hooks are defined as JSON objects. Please note that in order to be considered va
  * `response-headers` - specifies the list of headers in format `{"name": "X-Example-Header", "value": "it works"}` that will be returned in HTTP response for the hook
  * `success-http-response-code` - specifies the HTTP status code to be returned upon success
  * `incoming-payload-content-type` - sets the `Content-Type` of the incoming HTTP request (ie. `application/json`); useful when the request lacks a `Content-Type` or sends an erroneous value
+ * `http-methods` - a list of allowed HTTP methods, such as `POST` and `GET`
  * `include-command-output-in-response` - boolean whether webhook should wait for the command to finish and return the raw output as a response to the hook initiator. If the command fails to execute or encounters any errors while executing the response will result in 500 Internal Server Error HTTP status code, otherwise the 200 OK status code will be returned.
  * `include-command-output-in-response-on-error` - boolean whether webhook should include command stdout & stderror as a response in failed executions. It only works if `include-command-output-in-response` is set to `true`.
  * `parse-parameters-as-json` - specifies the list of arguments that contain JSON strings. These parameters will be decoded by webhook and you can access them like regular objects in rules and `pass-arguments-to-command`.

docs/Hook-Examples.md

@@ -287,12 +287,12 @@ __Not recommended in production due to low security__
 ]
 ```
 
-# JIRA Webhooks
+## JIRA Webhooks
 [Guide by @perfecto25](https://sites.google.com/site/mrxpalmeiras/notes/jira-webhooks)
 
-# Pass File-to-command sample
+## Pass File-to-command sample
 
-## Webhook configuration
+### Webhook configuration
 
 <pre>
 [
@@ -315,7 +315,7 @@ __Not recommended in production due to low security__
 ]
 </pre>
 
-## Sample client usage 
+### Sample client usage 
 
 Store the following file as `testRequest.json`. 
 
@@ -424,3 +424,97 @@ Travis sends webhooks as `payload=<JSON_STRING>`, so the payload needs to be par
   }
 ]
 ```
+
+## XML Payload
+
+Given the following payload:
+
+```xml
+<app>
+  <users>
+    <user id="1" name="Jeff" />
+    <user id="2" name="Sally" />
+  </users>
+  <messages>
+    <message id="1" from_user="1" to_user="2">Hello!!</message>
+  </messages>
+</app>
+```
+
+```json
+[
+  {
+    "id": "deploy",
+    "execute-command": "/root/my-server/deployment.sh",
+    "command-working-directory": "/root/my-server",
+    "trigger-rule": {
+      "and": [
+        {
+          "match": {
+            "type": "value",
+            "parameter": {
+              "source": "payload",
+              "name": "app.users.user.0.-name"
+            },
+            "value": "Jeff"
+          }
+        },
+        {
+          "match": {
+            "type": "value",
+            "parameter": {
+              "source": "payload",
+              "name": "app.messages.message.#text"
+            },
+            "value": "Hello!!"
+          }
+        },
+      ],
+    }
+  }
+]
+```
+
+## Multipart Form Data
+
+Example of a [Plex Media Server webhook](https://support.plex.tv/articles/115002267687-webhooks/).
+The Plex Media Server will send two parts: payload and thumb.
+We only care about the payload part.
+
+```json
+[
+  {
+    "id": "plex",
+    "execute-command": "play-command.sh",
+    "parse-parameters-as-json": [
+      {
+        "source": "payload",
+        "name": "payload"
+      }
+    ],
+    "trigger-rule":
+    {
+      "match":
+      {
+        "type": "value",
+        "parameter": {
+          "source": "payload",
+          "name": "payload.event"
+        },
+        "value": "media.play"
+      }
+    }
+  }
+]
+
+```
+
+Each part of a multipart form data body will have a `Content-Disposition` header.
+Some example headers:
+
+```
+Content-Disposition: form-data; name="payload"
+Content-Disposition: form-data; name="thumb"; filename="thumb.jpg"
+```
+
+We key off of the `name` attribute in the `Content-Disposition` value.

docs/Hook-Rules.md

@@ -186,7 +186,60 @@ For the regex syntax, check out <http://golang.org/pkg/regexp/syntax/>
 }
 ```
 
-### 4. Match Whitelisted IP range
+Note that if multiple signatures were passed via a comma separated string, each
+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
+```json
+{
+  "match":
+  {
+    "type": "payload-hash-sha256",
+    "secret": "yoursecret",
+    "parameter":
+    {
+      "source": "header",
+      "name": "X-Signature"
+    }
+  }
+}
+```
+
+Note that if multiple signatures were passed via a comma separated string, each
+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
+```json
+{
+  "match":
+  {
+    "type": "payload-hash-sha512",
+    "secret": "yoursecret",
+    "parameter":
+    {
+      "source": "header",
+      "name": "X-Signature"
+    }
+  }
+}
+```
+
+Note that if multiple signatures were passed via a comma separated string, each
+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
 
 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`.
 
@@ -200,7 +253,7 @@ The IP can be IPv4- or IPv6-formatted, using [CIDR notation](https://en.wikipedi
 }
 ```
 
-### 5. Match scalr-signature
+### 7. 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.

docs/Referencing-Request-Values.md

@@ -68,6 +68,34 @@ There are four types of request values:
 
     If the payload contains a key with the specified name "commits.0.commit.id", then the value of that key has priority over the dot-notation referencing.
 
+3. XML Payload
+
+    Referencing XML payload parameters is much like the JSON examples above, but XML is more complex.
+    Element attributes are prefixed by a hyphen (`-`).
+    Element values are prefixed by a pound (`#`).
+
+    Take the following XML payload:
+
+    ```xml
+    <app>
+      <users>
+        <user id="1" name="Jeff" />
+        <user id="2" name="Sally" />
+      </users>
+      <messages>
+        <message id="1" from_user="1" to_user="2">Hello!!</message>
+      </messages>
+    </app>
+    ```
+
+    To access a given `user` element, you must treat them as an array.
+    So `app.users.user.0.name` yields `Jeff`.
+
+    Since there's only one `message` tag, it's not treated as an array.
+    So `app.messages.message.id` yields `1`.
+
+    To access the text within the `message` tag, you would use: `app.messages.message.#text`.
+
 If you are referencing values for environment, you can use `envname` property to set the name of the environment variable like so
 ```json
 {
@@ -98,4 +126,4 @@ and for query variables you can use
 {
   "source": "entire-query"
 }
-```
+```

docs/Webhook-Parameters.md

@@ -3,36 +3,60 @@
 Usage of webhook:
   -cert string
         path to the HTTPS certificate pem file (default "cert.pem")
+  -cipher-suites string
+        comma-separated list of supported TLS cipher suites
+  -debug
+        show debug output
   -header value
         response header to return, specified in format name=value, use multiple times to set multiple headers
   -hooks value
         path to the json file containing defined hooks the webhook should serve, use multiple times to load from different files
   -hotreload
         watch hooks file for changes and reload them automatically
+  -http-methods string
+        globally restrict allowed HTTP methods; separate methods with comma
   -ip string
         ip the webhook should serve hooks on (default "0.0.0.0")
   -key string
         path to the HTTPS certificate private key pem file (default "key.pem")
+  -list-cipher-suites
+        list available TLS cipher suites
+  -logfile string
+        send log output to a file; implicitly enables verbose logging
   -nopanic
         do not panic if hooks cannot be loaded when webhook is not running in verbose mode
+  -pidfile string
+        create PID file at the given path
   -port int
         port the webhook should serve hooks on (default 9000)
   -secure
         use HTTPS instead of HTTP
+  -setgid int
+        set group ID after opening listening port; must be used with setuid
+  -setuid int
+        set user ID after opening listening port; must be used with setgid
   -template
         parse hooks file as a Go template
+  -tls-min-version string
+        minimum TLS version (1.0, 1.1, 1.2, 1.3) (default "1.2")
   -urlprefix string
         url prefix to use for served hooks (protocol://yourserver:port/PREFIX/:hook-id) (default "hooks")
   -verbose
         show verbose output
   -version
         display webhook version and quit
+  -x-request-id
+        use X-Request-Id header, if present, as request ID
+  -x-request-id-limit int
+        truncate X-Request-Id header to limit; default no limit
 ```
 
 Use any of the above specified flags to override their default behavior.
 
 # Live reloading hooks
-If you are running an OS that supports USR1 signal, you can use it to trigger hooks reload from hooks file, without restarting the webhook instance.
+If you are running an OS that supports the HUP or USR1 signal, you can use it to trigger hooks reload from hooks file, without restarting the webhook instance.
 ```bash
 kill -USR1 webhookpid
-```
+
+kill -HUP webhookpid
+```