Receive webhooks and trigger actions based on them.
Go to file
finga faba2949d2
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
cargo: Bump hmac and sha2 dependencies.
Bump the `hmac` dependency to `0.12`, therefor remove deprecated
`NewMac`. Further, bump the `sha2` dependency to `0.10`.
2023-06-11 22:37:25 +02:00
.gitea/issue_template Add gitea issue templates 2021-06-30 23:27:29 +02:00
debian Build a Debian package 2021-04-17 00:08:11 +02:00
src cargo: Bump hmac and sha2 dependencies. 2023-06-11 22:37:25 +02:00
.gitignore Parse JSON from post request 2021-02-02 11:17:27 +01:00
.woodpecker.yml ci: Update CI config 2022-10-15 01:56:07 +02:00
Cargo.lock cargo: Bump hmac and sha2 dependencies. 2023-06-11 22:37:25 +02:00
Cargo.toml cargo: Bump hmac and sha2 dependencies. 2023-06-11 22:37:25 +02:00
config.yml Increase version to 0.1.2 2021-11-10 10:50:59 +01:00 ci: Add a basic ci config 2022-02-10 00:56:49 +01:00
Rocket.toml Set server ident in headers 2021-11-26 11:44:59 +01:00
webhookey.1 Create the webhookey manpage 2021-11-26 11:59:47 +01:00



Webhookey is a web server listening for webhooks 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.


Install Rust

Install the Rust toolchain from

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 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 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


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.


  enabled: true


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.


    command: /usr/bin/local/ {{ /repository/name }}
    signature: X-Gitea-Signature
      - secret_key_01
      - secret_key_02
        - not:
              pointer: /ref
              regex: refs/heads/dev
        - and:
          - json:
              pointer: /ref
              regex: refs/heads/a_branch
          - header:
              field: X-Gitea-Event
              regex: push

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


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.


    - "::1"
    - "::1"

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


Configure a list of secrets to validate the hook.


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