webhookey/README.md

# Webhookey
Webhookey is a web server listening for requests as for example sent by
gitea's webhooks. Further, Webhookey allows you to specify rules
which are matched against the data received to trigger certain
actions.

## Build

### Install Rust
Install the Rust toolchain from [rustup.rs](https://rustup.rs).

### Build Webhookey
The Webhookey project can be built for development:
``` sh
    cargo b
```

or for releasing:
``` sh
    cargo b --release
```

### Install Webhookey
When a Rust toolchain installed you can also install Webhookey
directly without cloning it manually:
``` sh
    cargo install --git https://git.onders.org/finga/webhookey.git webhookey
```

or from within the project:
``` sh
    cargo install webhookey
```

### Run Webhookey
Webhookey can either be run from the project directory with:
``` sh
    cargo b
```

or you can copy the produced binary somewhere else from
`webhookey/target/{debug,release}/webhookey` depending on which one
you built.

## Configuration
Configuration syntax is YAML and it's paths as well as it's
configuration format is described in the following sections.

### Configuration Paths
Following locations are checked for a configuration file:
- `/etc/webhookey/config.yml`
- `<config_dir>/webhookey/config.yml`
- `./config.yml`

Whereas `<config_dir>` depends on the platform:
- Linux:   `$XDG_CONFIG_HOME` or `$HOME/.config`
- macOS:   `$HOME/Library/Application Support`
- Windows: `{FOLDERID_RoamingAppData}`

### Configuration parameters

#### Metrics
A metrics page can optionally enabled to query stats of the currently
running webhookey instance. Note that stats are lost between restarts
of webhookey as those are not stored persistently.

Example:
```yaml
metrics:
  enabled: true
  ip_filter:
    allow:
      - 127.0.0.1/31
```

#### Hooks
With `hooks` you can configure a sequence of hooks. A single hook
consists of the following fields:
- `command`: A command to be executed if a filter matches
- `allow`/`deny`: An optional parameter to either allow or deny
  specific source addresses or ranges.
- `signature`: Name of the HTTP header field containing the signature.
- `secrets`: List of secrets.
- `filter`: Tree of filters.

Example:
```yaml
hooks:
  hook1:
    command: /usr/bin/local/script_xy.sh {{ /repository/name }}
    signature: X-Gitea-Signature
    ip_filter:
      allow:
        - 127.0.0.1
        - 127.0.0.1/31
    secrets:
      - secret_key_01
      - secret_key_02
    filter:
      or:
        - not:
            json:
              pointer: /ref
              regex: refs/heads/dev
        - and:
          - json:
              pointer: /ref
              regex: refs/heads/a_branch
          - header:
              field: X-Gitea-Event
              regex: push
```

##### Command
To pass data to a command following two different methods can be used.

Example: `script_foo {{ header X-Gitea-Event }} {{ /field/foo }}`

###### JSON Pointers
Use JSON pointers ([RFC 6901](https://tools.ietf.org/html/rfc6901))
point to values of a JSON field from the JSON data.

Example: `{{ /field/pointed/to }}`.

###### Header
Use values from header fields sent with the HTTP request.

Example: `{{ header X-Gitea-Event }}`.

##### Allow and Deny
To allow or deny specific network ranges source is an optional
configuration parameter which either contains an allow or a deny field
with sequences containing networks. Note that IPv6 addresses have to
be put in single quotes due to the colons.

Example:
```yaml
allow:
  - 127.0.0.1
  - 127.0.0.1/31
  - "::1"
```

```yaml
deny:
  - 127.0.0.1
  - 127.0.0.1/31
  - "::1"
```

##### Signature
Set the name of the HTTP header field containing the HMAC signature.

##### Secrets
Configure a list of secrets to validate the hook.

##### Filter
Filter can be either a concrete filter or a conjunction
filter. Concrete filters return either true or false on specific
constraints. Conjunction filters contain lists of filters which are
evaluated and combined based on the type. The result is either used
for parent conjunction filters or, if at the root, used to decide if a
hook should be executed.

###### Conjunction Filters
Conjunction filters contain lists of other filters.
- `not`: Logical negation.
- `and`: Logical conjunction.
- `or`: Logical disjunction.

###### Concrete Filters
- `header`:

  The `header` filter matches a regular expression on a field from the
  received http(s) request header.

  - `field`: The header field which should be matched.
  - `regeq`: Regular expression which has to match the specified
    header field.

- `json`:

  The `json` filter matches a regular expression on a field from the
  received JSON data.

  - `pointer`: Pointer to the JSON field according to [RFC
    6901](https://tools.ietf.org/html/rfc6901).
  - `regex`: Regular expression which has to match the field pointed
    to by the pointer.