Guide · Open source
How to use webhook: set up hooks that run commands on your server
Updated · written with AI from the project's own documentation and checked against our catalogue data
webhook is a lightweight tool, written in Go, that creates HTTP endpoints on your server and runs a command you configure when a request reaches one of them. It is aimed at developers and operators who want something like a repository push to trigger a redeploy script on their own machine. After this guide you will know how to install it, write a basic hooks.json file, start the server, and add a trigger rule so that strangers cannot run your command.
webhookadnanh/webhook · ★ 12.2k · MIT Install options & downloads Quick start
- 1Install webhook. Install it with apt on Ubuntu or Debian, pkg on FreeBSD, or build from source with Go 1.21 or newer.
- 2Write hooks.json. Create an array with an id and an execute-command for each hook.
- 3Make the script executable. Begin your script with a #!/bin/sh shebang so webhook can run it.
- 4Start the server. Run webhook with -hooks pointing at your file, and add -verbose while testing.
- 5Send a test request. Send an HTTP GET or POST to http://yourserver:9000/hooks/your-hook-id to confirm the command runs.
- 6Add a trigger rule. Set trigger-rule, such as a required secret, before exposing the endpoint to others.
- 7Secure transport. Use -secure with certificate and key files, or place webhook behind a reverse proxy.
Install webhook on Ubuntu, FreeBSD or from source
On Ubuntu (17.04 or later) and Debian ("stretch" or later), you can install the community-packaged version with apt. On FreeBSD, use the pkg command. Both options are listed in the project README.
If you prefer to build it yourself, you need Go 1.21 or newer. Prebuilt binaries for different architectures are also available on the GitHub Releases page.
- Ubuntu or Debian: install the community package.
- FreeBSD: install with pkg.
- Snap Store: a listing is available.
- From source: requires Go 1.21 or newer.
sudo apt-get install webhook
pkg install webhook
go build github.com/adnanh/webhookCreate a hooks.json file that defines your hook
Start with an empty file named hooks.json. It holds an array of hooks. Each hook needs an id, which becomes part of its URL, and an execute-command, which is the script to run. The example below defines a hook named redeploy-webhook that runs /var/scripts/redeploy.sh from the working directory /var/webhook.
Make sure your script starts with a #!/bin/sh shebang line. If you prefer YAML, the README shows an equivalent hooks.yaml file. The full list of hook properties is in the project's Hook Definition page.
[
{
"id": "redeploy-webhook",
"execute-command": "/var/scripts/redeploy.sh",
"command-working-directory": "/var/webhook"
}
]Start webhook and test the endpoint
Run webhook and point it at your hooks file. The -verbose flag gives more output, which helps when you are debugging. By default the server listens on port 9000, so the example hook is served at http://yourserver:9000/hooks/redeploy-webhook.
A simple HTTP GET or POST request to that endpoint executes the script. Because anyone who knows the URL can do the same, do not leave a hook like this open on a real server. Add a trigger rule first (see the next section).
- Default port: 9000.
- Endpoint pattern: /hooks/ followed by the hook id.
- Other settings such as IP, port and hot reload are set with startup parameters described in the Webhook Parameters page.
/path/to/webhook -hooks hooks.json -verboseProtect hooks with trigger rules
The trigger-rule property sets the conditions a request must meet before the hook runs. The README's example is a secret that the caller must supply as a parameter. Without a rule, the hook fires for any request to its URL.
The project's Hook Rules page lists all available rules and how to use them. Treat trigger rules as required for any hook that runs on a server you care about.
- Use trigger-rule to require a secret or other condition.
- Without a rule, anyone who knows the endpoint can run the command.
- Check the Hook Rules page for the full list.
Pass request data to your command
webhook parses the request headers, payload and query variables, then passes the values you specify to your command, either as command-line arguments or as environment variables. Everything after that is up to your script. The project says it is designed to do only these steps and nothing more.
For form uploads, form values are added to the payload scope automatically. Files are ignored unless they have a Content-Type of application/json or are named in the parse-parameters-as-json setting, in which case they are parsed as JSON.
- Headers, payload and query variables can be passed to the command.
- Arguments can go on the command line or into environment variables.
- Multipart forms: values are added to payload; JSON files are parsed when criteria are met.
Run webhook over HTTPS, behind a proxy or under systemd
By default webhook serves plain http. Add the -secure flag and supply -cert and -key files to serve https. If your certificate comes from a certificate authority, the cert file should contain your server certificate followed by the CA certificate.
You can also run webhook behind a reverse proxy such as Nginx or Apache httpd, either on a TCP port or a Unix socket (-socket flag). The README warns that the ip-whitelist rule then checks the proxy's address, not the client's, so client IP restrictions must be enforced in the proxy. On systemd systems, webhook supports socket activation and uses the systemd-managed socket automatically.
- HTTPS: -secure, -cert /path/to/cert.pem, -key /path/to/key.pem.
- Unix socket: -socket flag.
- CORS headers: -header name=value flag.
- Socket activation is supported under systemd.
/path/to/webhook -hooks hooks.json -secure -cert /path/to/cert.pem -key /path/to/key.pemWhat people use it for
- Run a redeploy script on a staging server when changes are pushed to the master branch of a GitHub or Bitbucket project.
- Trigger a local build or deploy from a Slack or Mattermost outgoing webhook or slash command.
- Expose a simple endpoint that runs a maintenance command on a server you control.
- Pass request headers or payload fields to a shell script as arguments or environment variables.
Frequently asked questions
Is webhook free to use?
webhook is released under the MIT licence, which the project lists alongside its source. The README does not mention paid tiers. You run it on your own server, so you are responsible for hosting it.
How do I install webhook on Ubuntu?
On Ubuntu 17.04 or later, run sudo apt-get install webhook. This installs a community-packaged version. You can also build from source with Go 1.21 or newer using go build github.com/adnanh/webhook.
How do I make webhook secure?
Add a trigger-rule to each hook, such as a secret the caller must supply. Use -secure with -cert and -key to serve over HTTPS. The README warns that hooks without rules let anyone who knows the endpoint run the command.
Why does webhook not work behind a reverse proxy?
The ip-whitelist trigger rule checks the address of the proxy, not the client, when webhook sits behind one. You need to enforce client IP limits in the proxy itself. Check that your proxy forwards requests to the correct port or socket.
What is the difference between webhook and Hookdeck?
webhook receives requests, checks rules and runs a command on your server. Hookdeck is an event gateway that also queues, transforms, and replays webhooks. The README says webhook does not do queuing or replay.
Can webhook run in Docker?
The README lists community Docker images, including almir/webhook and roxedus/webhook, and says you can also create your own. It points to a discussion about the approach before you do.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use webhook if you want a small, configurable server that runs your own scripts when a request arrives, such as a deploy on push. Skip it if you need a hosted service, queuing, replay, or a setup where you cannot maintain a server and write shell scripts.
Install options & downloads