rehook
Rehook - a webhook dispatcher, filtering incoming requests from external services and acting on them.
Initial version created during the Gopher Gala. Rehook
finished in second place and won the Best Solo App prize. See the
gophergala.2015.entry tag in this repo for the version that was originally
submitted.
About
External web services often provide webhooks as an alternative to polling their public API's for up-to-date information. For example, commits being pushed to Github, bounced emails when sending automated messages through email services, or chat messages matching a certain filter.
However, you don't want to deal with all the different formats, validations and building filters for each of those services on every system that is interested in this information. Some systems might not even be directly reachable from the internet.
Rehook provides a central, public web endpoint that receives all those webhook requests. It can validate them to prevent abuse, filter them for certain conditions or rate-limit incoming requests. You can configure actions that should take place afterwards, such as forwarding the request to multiple hosts, storing them for later analysis or sending an email based on a template.
It provides an easy to use web interface to configure your webhooks and to keep an eye on how much traffic is being handled.
Building from source
Assuming you have installed a recent version of Go, you can simply run
go get github.com/jstemmer/rehook
This will download Rehook to $GOPATH/src/github.com/jstemmer/rehook. In
this directory run go build to create the rehook binary.
Running
Simply start the rehook binary in the directory where you downloaded Rehook.
When running the binary from elsewhere, make sure to copy the public and
views directories, as they contain the files required for the admin web
interface.
By default, Rehook will listen to http://localhost:9000 for incoming webhook requests. The admin interface where you can configure Rehook is available on http://localhost:9001/.
You should make sure to prevent unauthorized access to the administration port. In the future we will replace this with proper user management and authentication.
You can configure these ports and the location of the database file.
$ ./rehook -help
Usage of ./rehook:
-admin=":9001": Private HTTP listen address for admin interface
-db="data.db": Database file to use
-http=":9000": Public HTTP listen address for incoming webhooks
Configuring your first webhook
Open the admin interface in your browser, http://localhost:9001 by default.
Every hook you create must have a unique identifier, Rehook will listen on the
public port for incoming requests on the /h/<identifier> path.
Click the Create new hook button to create a new webhook. Enter a suitable
hook identifier, for example github. Rehook will now accept HTTP requests on
http://localhost:9000/h/github.
You can now add components to process incoming requests. The arrow indicates the order in which the request flows through the components. If a component cannot handle a request, it will give a reason and further processing is stopped.
Since this webhook will accept Github webhook requests, let's first add a
Github validator component. This component makes sure that the incoming
request is actually from Github by calculating the signature of the request
data and comparing it to the signature in the request header. The secret you
enter here must be the same as the secret you will enter on the Github webhook
page.
Let's log the request and write it to a file. Add the Log and Write to file
components. The last one will write a file for each request in the log/
directory. Your page should now look something like this.
Go to the Github settings page of your repository, click the Webhooks & Services button and add a new Webhook. Enter the URL where your Rehook
instance can be reached, be sure to use /h/github as the path. Click Add webhook and, if everything was setup correctly, your first webhook request was
just handled by Rehook.
Components
The following components are currently available:
Send email (using Mailgun)
Sends an email with a custom body template to the specified address using the Mailgun API.
Execute command
Executes a command on the local server using sh and logs the output to
stderr.
Forward request
Forwards the request, including its headers, to the specified URL.
Github validator
Calculates the SHA1 HMAC of the body and compares it to the X-Hub-Signature
header. In addition, it makes sure the X-Github-Delivery header is unique to
prevent replay attacks.
Log
Logs a message to stderr.
Mailgun validator
Calculates the SHA256 HMAC of the timestamp and random token in the request
body and compares it to the signature. It also verifies the token is unique
to prevent replay attacks.
Rate limiter
The rate limiter accepts a certain number of requests in a configurable interval. Incoming requests exceeding this limit will be dropped.
Write to file
Writes the contents of the request to a file in the log/ directory. This
makes it easy to view the request details later.
License
MIT, see the LICENSE file.