README.md

Hooka is a webhook server written in Node, which allows you to easily create HTTP endpoints to trigger the execution of configured commands.

Installation

$ npm install -g hooka

Features

• Zero coding
• Pass request data to the command
• Set validation rules to trigger hooks only under certain circumstances
• TLS/SSL support

Documentation

• CLI options
• Webhooks JSON
• Recipes
  • Bitbucket
  • GitHub
  • Slack

Basic usage

1. Create a webhooks.json file:

   Windows users: Replace $MESSAGEwith %MESSAGE%

[
    {
        "method": ["GET", "POST"],
        "path": "/hello",
        "command": "echo Hello world"
    },
    {
        "method": "POST",
        "path": "/hello-again",
        "command": "echo Hello from the other side: $MESSAGE",
        "validate": [
            {
                "source": "jsonBody",
                "find": "payload.token",
                "match": "exactly",
                "value": "MySecret"
            }
        ],
        "parseJson": [
            {
                "query": "payload.hello",
                "variable": "MESSAGE"
            }
        ]
    }
]

1. Start Hooka in the same directory:

$ hooka

1. Open http://localhost:3000/hello in your browser to trigger the first hook.

2. Trigger the second hook with a POST request in a new terminal window:

$ curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"hello": "I love cupcakes", "token": "MySecret"}' \
    http://localhost:3000/hello-again

1. Now if you go back to your terminal where Hooka is running, you should see something like:

With Docker

Replace /path/to/webhooks.json with the actual path to your webhooks JSON file.

$ docker run -v /path/to/webhooks.json:/src/webhooks.json -p 3000:3000 danistefanovic/hooka

Security

Since anyone could in principle send requests to your webhook server, it’s important to implement some basic security steps to keep your webhooks safe. Here are some tips that can help reduce the risks:

• Enable TLS/SSL if the transmitted data is sensitive or if you wish to protect against replay attacks
• Use validation rules to verify that the requests originated from the expected source. For example:
  • Enable HMAC based validation with the hmac-sha1 match type
  • Send a custom token in the payload or as a HTTP header which has to match exactly
• Obscurity as a security layer:
  • Set hook paths which are not easy to guess
  • Be creative with the HTTP method for the webhook

License

Do whatever you want with it, but don't blame me for anything that goes wrong.

MIT © Daniel Stefanovic