[opensourcedex]

webhook is a free, open source cloud infrastructure management project written in Go and released under MIT. It has 12,134 GitHub stars, 875 forks and 127 open issues, and was last pushed 13 days ago. On this registry it ranks #14 of 43 tracked projects in Cloud Infrastructure Management, with 5 head-to-head comparisons available.

What is webhook?

webhook is a lightweight, MIT-licensed incoming webhook server written in Go that exposes HTTP endpoints which execute configured shell commands, built for developers and operators who want a push from GitHub, Bitbucket, Slack, or Mattermost to run a deploy or maintenance script on their own server.

What it is

webhook is a small, configurable program written in Go that creates HTTP endpoints on a server and runs a command when those endpoints are called. It reads a JSON or YAML configuration file describing one or more hooks, each identified by an id, an execute-command, and a command-working-directory. When a request arrives, it parses the headers, payload, and query variables, checks whether the rules declared for that hook are satisfied, and then passes the specified arguments to the command, either as command line arguments or as environment variables. Its stated scope is deliberately narrow: receive the request, parse it, check the rules, and hand off to the command.

The concrete problem it solves is replacing a bespoke HTTP listener that glue-scripts a continuous integration provider into a deployment step. Instead of writing and hardening a custom endpoint that receives a GitHub or Bitbucket push event and then shells out to a redeploy script, a self-hoster writes a hook entry in hooks.json and points the provider's webhook URL at the generated endpoint. Everything downstream of argument passing, including what the command actually does with failures, is the responsibility of the command's author, not of webhook itself.

Key capabilities

  • Serves hooks from a single configuration file, accepted as either JSON (hooks.json) or YAML (hooks.yaml), containing an array of hook definitions.
  • Runs a configured command per hook through execute-command, with command-working-directory setting the working directory for that process.
  • Passes request data to the command, including HTTP headers, payload, and query variables, as command line arguments or environment variables.
  • Supports per-hook rules that must be satisfied before the hook is triggered, so a request can be rejected before any command runs.
  • Listens on port 9000 by default and exposes each hook at a predictable path such as http://yourserver:9000/hooks/redeploy-webhook.
  • Takes runtime overrides for IP, port, hook hot reload, and verbose output through documented command line parameters.
  • Ships as source buildable with go build github.com/adnanh/webhook against Go 1.21 or newer, and as prebuilt binaries for multiple architectures.

Who uses it and how

  • Teams running a staging server use it to trigger a redeploy script whenever changes are pushed to the master branch of a GitHub or Bitbucket project.
  • Chat-centric teams wire Slack or Mattermost outgoing webhook integrations or slash commands to it, then report results back into a channel through incoming webhook integrations or the response body.
  • Ubuntu users on 17.04 or later and Debian users on stretch or later install a community packaged build with sudo apt-get install webhook; FreeBSD users install with pkg install webhook; Snap users install from the Snap store.
  • Operators who prefer a single static binary download prebuilt releases and run them alongside their own scripts rather than maintaining a custom listener.

Getting started

Build from source with go build github.com/adnanh/webhook in a Go 1.21 or newer environment, or install the packaged version for Ubuntu, Debian, FreeBSD, or the Snap store. Then create hooks.json, run /path/to/webhook -hooks hooks.json -verbose, and the endpoint becomes reachable on port 9000.

How it compares

No paid products that this project replaces are listed in the facts, and the README's neighbouring categories, a scriptable webhook gateway and an event gateway, are described without naming competing tools. On the evidence provided, webhook stands alone in this registry as the minimal option.

When to use it — and when not to

A self-hoster must operate the server, the binary, the configuration file, and every script the hooks invoke, since webhook provides no queueing, retries, replay, or monitoring of its own. Anyone who needs durable ingestion, verification pipelines, or an auditable event history should look at a full event gateway instead, and anyone unwilling to write and maintain the target commands should not adopt it. The project is actively maintained with 12,132 stars, 875 forks, and 127 open issues as of its last push on 4 September 2026, but its narrow, intentional scope means missing conveniences are a design choice rather than a backlog item.

project readme (upstream, from github) — read inline

What is webhook? ![build-status][badge]

Webhook

[webhook][w] is a lightweight configurable tool written in Go, that allows you to easily create HTTP endpoints (hooks) on your server, which you can use to execute configured commands. You can also pass data from the HTTP request (such as headers, payload or query variables) to your commands. [webhook][w] also allows you to specify rules which have to be satisfied in order for the hook to be triggered.

For example, if you're using Github or Bitbucket, you can use [webhook][w] to set up a hook that runs a redeploy script for your project on your staging server, whenever you push changes to the master branch of your project.

If you use Mattermost or Slack, you can set up an "Outgoing webhook integration" or "Slash command" to run various commands on your server, which can then report back directly to you or your channels using the "Incoming webhook integrations", or the appropriate response body.

[webhook][w] aims to do nothing more than it should do, and that is:

  1. receive the request,
  2. parse the headers, payload and query variables,
  3. check if the specified rules for the hook are satisfied,
  4. and finally, pass the specified arguments to the specified command via command line arguments or via environment variables.

Everything else is the responsibility of the command's author.

Not what you're looking for?

hookdoo
Scriptable webhook gateway to safely run your custom builds, deploys, and proxy scripts on your servers. An event gateway to reliably ingest, verify, queue, transform, filter, inspect, monitor, and replay webhooks.

Getting started

Installation

Building from source

To get started, first make sure you've properly set up your Go 1.21 or newer environment and then run

$ go build github.com/adnanh/webhook

to build the latest version of the [webhook][w].

Using package manager

Snap store

Get it from the Snap Store

Ubuntu

If you are using Ubuntu linux (17.04 or later), you can install webhook using sudo apt-get install webhook which will install community packaged version.

Debian

If you are using Debian linux ("stretch" or later), you can install webhook using sudo apt-get install webhook which will install community packaged version (thanks @freeekanayaka) from https://packages.debian.org/sid/webhook

FreeBSD

If you are using FreeBSD, you can install webhook using pkg install webhook.

Download prebuilt binaries

Prebuilt binaries for different architectures are available at GitHub Releases.

Configuration

Next step is to define some hooks you want [webhook][w] to serve. [webhook][w] supports JSON or YAML configuration files, but we'll focus primarily on JSON in the following example. Begin by creating an empty file named hooks.json. This file will contain an array of hooks the [webhook][w] will serve. Check Hook definition page to see the detailed description of what properties a hook can contain, and how to use them.

Let's define a simple hook named redeploy-webhook that will run a redeploy script located in /var/scripts/redeploy.sh. Make sure that your bash script has #!/bin/sh shebang on top.

Our hooks.json file will now look like this:

[
  {
    "id": "redeploy-webhook",
    "execute-command": "/var/scripts/redeploy.sh",
    "command-working-directory": "/var/webhook"
  }
]

NOTE: If you prefer YAML, the equivalent hooks.yaml file would be:

- id: redeploy-webhook
  execute-command: "/var/scripts/redeploy.sh"
  command-working-directory: "/var/webhook"

You can now run [webhook][w] using

$ /path/to/webhook -hooks hooks.json -verbose

It will start up on default port 9000 and will provide you with one HTTP endpoint

http://yourserver:9000/hooks/redeploy-webhook

Check webhook parameters page to see how to override the ip, port and other settings such as hook hotreload, verbose output, etc, when starting the [webhook][w].

By performing a simple HTTP GET or POST request to that endpoint, your specified redeploy script would be executed. Neat!

However, hook defined like that could pose a security threat to your system, because anyone who knows your endpoint, can send a request and execute your command. To prevent that, you can use the "trigger-rule" property for your hook, to specify the exact circumstances under which the hook would be triggered. For example, you can use them to add a secret that you must supply as a parameter in order to successfully trigger the hook. Please check out the Hook rules page for detailed list of available rules and their usage.

Multipart Form Data

[webhook][w] provides limited support the parsing of multipart form data. Multipart form data can contain two types of parts: values and files. All form values are automatically added to the payload scope. Use the parse-parameters-as-json settings to parse a given value as JSON. All files are ignored unless they match one of the following criteria:

  1. The Content-Type header is application/json.
  2. The part is named in the parse-parameters-as-json setting.

In either case, the given file part will be parsed as JSON and added to the payload map.

Templates

[webhook][w] can parse the hooks configuration file as a Go template when given the -template CLI parameter. See the Templates page for more details on template usage.

Using HTTPS

[webhook][w] by default serves hooks using http. If you want [webhook][w] to serve secure content using https, you can use the -secure flag while starting [webhook][w]. Files containing a certificate and matching private key for the server must be provided using the -cert /path/to/cert.pem and -key /path/to/key.pem flags. If the certificate is signed by a certificate authority, the cert file should be the concatenation of the server's certificate followed by the CA's certificate.

TLS version and cipher suite selection flags are available from the command line. To list available cipher suites, use the -list-cipher-suites flag. The -tls-min-version flag can be used with -list-cipher-suites.

Running behind a reverse proxy

[webhook][w] may be run behind a "reverse proxy" - another web-facing server such as Apache httpd or Nginx that accepts requests from clients and forwards them on to [webhook][h]. You can have [webhook][w] listen on a regular TCP port or on a Unix domain socket (with the -socket flag), then configure your proxy to send requests for a specific host name or sub-path over that port or socket to [webhook][w].

Note that when running in this mode the ip-whitelist trigger rule will not work as expected, since it will be checking the address of the proxy, not the client. Client IP restrictions will need to be enforced within the proxy, before it decides whether to forward the request to [webhook][w].

CORS Headers

If you want to set CORS headers, you can use the -header name=value flag while starting [webhook][w] to set the appropriate CORS headers that will be returned with each response.

Running under systemd

On platforms that use systemd, [webhook][w] supports the socket activation mechanism. If [webhook][w] detects that it has been launched from a systemd-managed socket it will automatically use that instead of opening its own listening port. See the systemd page for full details.

Interested in running webhook inside of a Docker container?

You can use one of the following Docker images, or create your own (please read this discussion):

readme truncated — read the full docs on github

Frequently asked questions

Is webhook free to use?

webhook is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does webhook do?

webhook is a lightweight incoming webhook server to run shell commands

What is webhook written in?

webhook is primarily written in Go. Its source is publicly available at https://github.com/adnanh/webhook, and it has 12,134 GitHub stars.