Hookout - Reverse HTTP Webhooks

Developing webhook based applications from behind a firewall or NAT provides many challenges. The biggest is allowing external applications to see your hook. Hookout allows you to use a ReverseHTTP (www.reversehttp.net) server to expose your application to the outside world, without needing to configure any complicated firewall holes.

Getting Started

Installing

Hookout can be installed via RubyGems with:

gem sources -a http://gems.github.com
gem install paulj-hookout

It can also be installed manually with:

git clone git://github.com/paulj/hookout.git
cd hookout
rake build install

Running an application via the hookout helper

Hookout provides a Rack (rack.rubyforge.org) adapter, allowing any standard Rack application to be made available. It also bundles a script called hookout that will start up an instance of Thin using ReverseHTTP as a backend. This section will cover running a simple Sinatra application with the hookout helper.

Firstly, say we have a simple Sinatra application (called simple-app.rb):

require 'rubygems'
require 'sinatra'

get '/' do
  "Hello World"
end

To run with the hookout adapter, you’ll need a simple rackup configuration file. Create a config.ru such as:

require 'simple-app'

set :run, false

run Sinatra::Application

From the command line, you can now start this application with a command line such as:

hookout -a http://www.reversehttp.net/reversehttp -n simple-ruby-app -R config.ru start

Thin should boot, and provide output such as:

>> Thin web server (v1.0.0 codename That's What She Said)
>> Maximum connections set to 1024
>> Listening on simple-ruby-app via http://www.reversehttp.net/reversehttp, CTRL+C to stop
Bound to location http://simple-ruby-app.www.reversehttp.net/

You can now visit simple-ruby-app.www.reversehttp.net to see you application.

Configuring Sinatra to use Hookout as the default server

To make a Sintatra application run Hookout instead of thin, a simple script such as the following can be used:

require 'rubygems'
require 'sinatra'
require 'hookout'

set :server, 'hookout'
set :host, 'http://www.reversehttp.net/reversehttp'
set :port, 'standalone-ruby-app'

get '/' do
  "Hello World"
end

This instructs Sinatra to start Hookout as the Rack adapter; and informs hookout that it should use the public www.reversehttp.net server; and informs hookout that it should request the “standalone-ruby-app” space on that server for this application. (Note: To prevent problems, it is HIGHLY recommended to change this to something more unique before trying this!).

You can now run the application with:

ruby test-app.rb

You should see it startup with something like:

== Sinatra/0.9.2 has taken the stage on test-ruby-app for development with backup from Hookout
Location changed to http://standalone-ruby-app.www.reversehttp.net/

You can now visit standalone-ruby-app.www.reversehttp.net, and see you own Sinatra app serving pages!