4.5 KiB
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.
Build Webhookey
The Webhookey project can be built for development:
cargo b
or for releasing:
cargo b --release
Install Webhookey
When a Rust toolchain installed you can also install Webhookey directly without cloning it manually:
cargo install --git https://git.onders.org/finga/webhookey.git webhookey
or from within the project:
cargo install webhookey
Run Webhookey
Webhookey can either be run from the project directory with:
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:
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 matchesallow
/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:
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:
- json:
pointer: /ref
regex: refs/heads/master
- and:
- json:
pointer: /ref
regex: refs/heads/a_branch
- json:
pointer: /after
regex: f6e5fe4fe37df76629112d55cc210718b6a55e7e
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
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:
allow:
- 127.0.0.1
- 127.0.0.1/31
- "::1"
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.
and
: Logical conjunction.or
: Logical disjunction.
Concrete Filters
-
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.