adnanh/webhook: Running Shell Commands from HTTP Requests

What adnanh/webhook actually does, and who it is for

The project describes itself as a lightweight configurable tool written in Go that lets you create HTTP endpoints on your server and execute configured commands from them. The scope is deliberately narrow. The README lists four steps: receive the request, parse the headers, payload and query variables, check whether the specified rules for the hook are satisfied, then pass the specified arguments to the specified command via command line arguments or environment variables. Everything else is the responsibility of the command's author.

That boundary is the point. This is not a CI system, not a job queue and not an event gateway. It is the piece that sits between an HTTP caller and a script you already have. The README's own example is a redeploy script on a staging server that fires when changes land on the master branch of a project. Slack and Mattermost outgoing webhook integrations or slash commands are the other named use case, where a command runs on the server and reports back through an incoming webhook or a response body.

The intended user is someone who controls the server, can write the script, and wants the trigger logic to stay in a config file rather than in application code.

The request-to-command path in adnanh/webhook

A running instance reads a hooks file and serves one endpoint per hook. With the README's example, the hook id redeploy-webhook is reachable at http://yourserver:9000/hooks/redeploy-webhook, and the default port is 9000. The hook definition names the command to execute and the working directory it runs in.

Data from the request is not discarded. Headers, payload and query variables are parsed and can be passed to the command as command line arguments or as environment variables, which is what makes the tool useful beyond a bare trigger. Multipart form data gets limited support: the README states that all form values are automatically added to the payload scope, and that the parse-parameters-as-json setting parses a given value as JSON. File parts are ignored unless the Content-Type header is application/json or the part is named in parse-parameters-as-json, in which case the file part is parsed as JSON and added to the payload map.

Rule checking happens before execution. The trigger-rule property defines the exact circumstances under which a hook fires, and the README's own example is a secret that must be supplied as a parameter. This is the mechanism that separates a usable endpoint from an open remote command execution hole.

Installing adnanh/webhook and serving a first hook

The README gives several routes. Building from source needs a Go 1.21 or newer environment. The go.mod file declares go 1.21 with toolchain go1.22.0, so the module matches the stated requirement.

go build github.com/adnanh/webhook

Packaged installs exist for several systems. Ubuntu 17.04 or later and Debian stretch or later use apt-get, and the README notes those are community packaged versions rather than builds produced by the project. FreeBSD uses pkg. Prebuilt binaries for different architectures are on the GitHub Releases page.

sudo apt-get install webhook

Configuration is an array of hooks. The README's minimal example runs a redeploy script and sets the working directory:

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

YAML is supported as an alternative, with the same keys written as id, execute-command and command-working-directory. Start the server with the hooks file and verbose output:

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

The server starts on port 9000 and exposes the endpoint for the hook id. A GET or POST to that endpoint runs the script. The README warns directly that a hook defined this way is a security threat because anyone who knows the endpoint can execute the command, and points to trigger-rule for the fix. Add the rule before exposing the port.

Where adnanh/webhook is the wrong tool

The README is explicit that the tool aims to do nothing more than receive, parse, check and execute. That means there is no queue, no retry, no replay and no delivery guarantee between the HTTP caller and your script. If your script fails, the HTTP response is what the caller sees; the tool does not persist the event for a later attempt. For a redeploy that can be re-triggered by hand, that is acceptable. For a payment callback or an event you must not lose, it is not.

Security is the second boundary. Hook definitions without a trigger-rule are open to anyone who knows the URL, and the README says so plainly. The tool does not decide your network exposure for you. If the endpoint must be reachable from the public internet, the rule configuration and whatever sits in front of the port are your responsibility.

Third, the packaged versions are not the project's own builds. The README labels the Ubuntu and Debian packages as community packaged, so the version you get from apt-get may not match the release you read about. If version behaviour matters, build from source or take the release binary.

adnanh/webhook compared with an event gateway

The README's own comparison table places the project next to Hookdoo and Hookdeck. The difference is architectural rather than cosmetic. adnanh/webhook executes a command on the machine where it runs and returns whatever the command produces; it holds no state between requests.

Hookdeck is described in that table as an event gateway that ingests, verifies, queues, transforms, filters, inspects, monitors and replays webhooks. Hookdoo is described as a scriptable webhook gateway for running custom builds, deploys and proxy scripts on your servers. The practical split: if you need the event to survive a failure of your script, or you need to inspect and replay traffic, the gateway model covers that and adnanh/webhook does not. If you need a small binary on a host that already has the script, and you want the trigger logic in a file you control, the gateway adds a component you do not need.

There is also a general distinction worth keeping straight, since search traffic often conflates the terms. A webhook is a request pushed to an endpoint you own; an API is something you call. adnanh/webhook is on the receiving side of the first model.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-09-04, and the most recent release listed is 2.8.3 on 2026-02-12. The release before that, 2.8.2, is dated 2024-10-25, and 2.8.1 is dated 2023-05-22, so the release cadence has been uneven rather than steady.

The licence is MIT, which permits use, modification and redistribution with the licence text retained. That is a permissive arrangement, but it also means there is no warranty and no support obligation attached. The README describes no commercial support offering for the project itself.

Upgrade cost is low by construction. Configuration is a JSON or YAML array of hook definitions, and the module's dependencies are pinned in go.mod, so a rebuild from source is reproducible against those versions. The main operational cost is not the upgrade itself but the review that should accompany it: every hook's trigger-rule is security-relevant, and a config file that was written for an older version deserves a read before it is redeployed. The repository also ships hooks.json.example, hooks.yaml.example and template variants, which are the reference points for what a valid configuration looks like.

Editorial conclusion

Adopt adnanh/webhook if you need a small self-hosted endpoint that maps HTTP requests to scripts and you are willing to write the trigger rules and secure the port yourself. Do not adopt it if you need queuing, replay, delivery guarantees or a hosted dashboard; the README points to Hookdoo and Hookdeck for that class of work. Before deploying, verify the trigger-rule configuration for every hook and check whether the packaged version you install matches the release you expect, since the README notes that Ubuntu and Debian packages are community packaged.

Frequently asked questions

Official sources

1. adnanh/webhook on GitHub
2. Issues
3. License: MIT
4. README
5. Releases