webhookey/README.md

# Webhookey
Webhookey is a web server listening for
[webhooks](https://en.wikipedia.org/wiki/Webhook) 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. The `metrics`
structure is optional as well as the `ip_filter`. The `ip_filter`
supports either `allow` or `deny` containing a list of IPv4 and IPv6
addresses and networks.

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 }}`.

##### IP Filter
Specific IPv4 and IPv6 addresses and/or ranges ranges can be allowed
or denied. The `ip_filter` is optional and has to contain either an
`allow` or a `deny` field which contains a sequence of IPv4 or IPv6
addresses or CIDR network ranges. Note that IPv6 addresses have to be
quoted due to the colons.

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

```yaml
ip_filter:
  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.
  - `regex`: 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.