Skip to content

webhook webhook

webhook is a lightweight incoming webhook server to run shell commands

🛠 Installation

You can download pre-compiled binaries from the [GitHub releases page][2].

sudo apt install webhook

sudo apt install webhook

docker pull adnanh/webhook

brew install webhook

⚙ Config

webhook is configured using a single JSON or YAML file (e..g., hooks.json) that contains an array of hook definitions. A minimal hooks.json file looks like this:

hook.yaml

- id: redeploy-my-app
  execute-command: /var/scripts/redeploy.sh
  command-working-directory: /var/scripts/

hook.json

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

To secure your webhook, you should add a trigger-rule. A common method is to use a secret, which can be passed as a URL parameter or in the payload.

Here is a more secure example that triggers the hook only if the secret "my-secret-token" is provided:

hook.yaml

- id: redeploy-my-app
  execute-command: /var/scripts/redeploy.sh
  command-working-directory: /var/scripts/
  trigger-rule:
    match:
      type: value
      value: my-secret-token
      parameter:
        source: url
        name: secret

hook.json

[
  {
    "id": "redeploy-my-app",
    "execute-command": "/var/scripts/redeploy.sh",
    "command-working-directory": "/var/scripts/",
    "trigger-rule": {
      "match": {
        "type": "value",
        "value": "my-secret-token",
        "parameter": {
          "source": "url",
          "name": "secret"
        }
      }
    }
  }
]

📝 Usage

1. Run the Server

Start the webhook server, pointing it to your configuration file. By default, it runs on port 9000.

webhook -hooks /etc/webhook/hooks.json -verbose
  • -hooks: Specifies the path to your hook configuration file.
  • -verbose: (Optional) Provides detailed logging.

2. Trigger the Hook

You can trigger a hook by sending an HTTP POST request to its endpoint.

Simple Hook (no trigger rule)

curl -X POST http://your-server-ip:9000/hooks/redeploy-my-app

Secure Hook (with URL secret)

curl -X POST http://your-server-ip:9000/hooks/redeploy-my-app?secret=my-secret-token

The command specified in your hooks.json (/var/scripts/redeploy.sh in this example) will then be executed on the server.

🔗 References