Webhookey

Webhookey - trigger something by receiving webhooks. Webhookey is a web endpoint listening for webhooks. Further, Webhookey allows you to specify rules which, when matched, trigger certain actions.

Install

Webhookey binaries and a Debian package can be downloadad from the Releases page.

Build

Install Rust

Install the Rust toolchain from rustup.rs.

Build Webhookey

The Webhookey project can be built for development:

cargo b

or for releasing:

cargo b --release

Install Webhookey

Webhookey can be installed directly without cloning it manually:

cargo install --git https://git.onders.org/finga/webhookey.git webhookey

Or from the project path:

cargo install --path .

Run Webhookey

Webhookey can either be started from the project path:

cargo r

Dabian Packages

The cargo-deb helper builds a Debian package.

cargo install cargo-deb
cargo deb

Configuration

Configuration Paths

Following locations are checked for a configuration file when starting:

• /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 Format

Here is an example configuration

metrics:
  enabled: true
  ip_filter:
    allow:
      - 127.0.0.1/31
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

Metrics

A metrics page allows querying stats of the currently running webhookey instance. Note that stats are not persistent and are lost when webhookey restarts. 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.

metrics:
  enabled: true
  ip_filter:
    allow:
      - 127.0.0.1/31

Hooks

The hooks structure contains all hooks, e.g. triggers or actions. A single hook has the following configuration 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.

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) point to values of a JSON field from the JSON data.

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

Header

The content of header fields that are received in the request containing a webhook can be used wit the header keyword.

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

IP Filter

Specific IPv4 and IPv6 addresses and/or 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.

ip_filter:
  allow:
    - 127.0.0.1
    - 127.0.0.1/31
    - "::1"

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 that validate the webhook.

Filter

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

Conjunction of Filters

Conjunction of 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.
  • regex: Regular expression which has to match the field pointed to by the pointer.