wip

docs/Hook-Definition.md

@@ -22,7 +22,7 @@ Hooks are defined as objects in the JSON or YAML hooks configuration file. Pleas
 * `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
- * `pre-hook-command` - specifies the command that will be run before the hook gets invoked.
+ * `pre-hook-command` - specifies the command that will be run before the hook gets invoked. Check [Pre-hook command page](PreHook-Command.md) for more details and examples.
    * to the STDIN of this command, webhook will pass a JSON string representation of an object with the following properties:
      * `hookID` - ID of the hook that got matched
      * `method` - HTTP(s) method used by the client (i.e. GET, POST, etc...)
@@ -33,6 +33,7 @@ Hooks are defined as objects in the JSON or YAML hooks configuration file. Pleas
      * `headers` - object with headers and their respective values
      * `base64EncodedBody` - base64 encoded request body
     * Output of this command __MUST__ be valid JSON string which will be parsed by the webhook and accessible using the `pre-hook` as source when referencing values. 
+    * __Important! Any errors encountered while trying to execute the pre-hook command will prevent the hook from triggering!__
 
 ## Examples
 Check out [Hook examples page](Hook-Examples.md) for more complex examples of hooks.

docs/PreHook-Command.md

@@ -0,0 +1,62 @@
+# Pre-hook command
+To the STDIN of the pre-hook command, webhook will pass a JSON string representation of an object with the following properties:
+ * `hookID` - ID of the hook that got matched
+ * `method` - HTTP(s) method used by the client (i.e. GET, POST, etc...)
+ * `URI` - URI which client requested
+ * `host` - value of the `Host` header sent by the client
+ * `remoteAddr` - client's IP address and port in the `IP:PORT` format
+ * `query` - object with query parameters and their respective values
+ * `headers` - object with headers and their respective values
+ * `base64EncodedBody` - base64 encoded request body
+
+_Please note!_ Output of this command __MUST__ be valid JSON string which will be parsed by the webhook and accessible using the `pre-hook` as source when referencing values. 
+
+__Important! Any errors encountered while trying to execute the pre-hook command will prevent the hook from triggering!__
+
+# Examples
+
+_Please note:_ Following examples use shell scripts as pre-hook commands, but it is possible to use ruby, python, or anything else you like, as long as it outputs a valid JSON string as the result.
+
+_Make sure you have the `jq` command available, as we're using it to parse the JSON in the pre-hook script._
+
+## Getting the IP address of the requester
+<details>
+    <summary>script.sh</summary>
+    
+    ```sh
+    #!/bin/bash
+
+    ip=$1
+    
+    echo $ip >> ips.txt
+    ```
+</details>
+<details>
+    <summary>prehook.sh</summary>
+    
+    ```sh
+    #!/bin/bash
+    
+    context=$(cat)
+    ip=`echo $context | jq -r '.remoteAddr' | cut -d ':' -f 1`
+    
+    echo "{\"ip\": \"$ip\"}"
+    ```
+</details>
+
+<details>
+    <summary>hooks.json</summary>
+    
+    ```json
+    [
+        {
+            "id": "log-ip",
+            "pre-hook-command": "/home/example/prehook.sh",
+            "execute-command": "/home/example/script.sh",
+            "pass-arguments-to-command": [
+                { "source": "pre-hook", "name": "ip" }
+            ]
+        }
+    ]
+    ```
+</details>

docs/Referencing-Request-Values.md

@@ -2,7 +2,7 @@
 There are four types of request values:
 
 1. Pre-hook values
-   These are the values provided by the `pre-hook-command` output.
+   These are the values provided by the `pre-hook-command` output. More details on the pre-hook command can be found [here](PreHook-Command.md).
    
    ```json
    {