Asynchronous HTTP request dispatcher for webhooks
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin moved HookahRequest into root of hookah module, added yaml config loader Nov 14, 2009
hookah fixing typo in merge conflict Nov 28, 2009
.gitignore no egg info plz Nov 14, 2009
LICENSE Added license file. Aug 5, 2009 Added license file. Aug 5, 2009
TODO replaced cherrypy with twisted Apr 25, 2009 requires pyyaml, increment to 0.1.0, distutils to setuptools Nov 14, 2009


The HTTP event engine

Current Features

  • Interface is 100% HTTP (use easily from any language)
  • Dispatches POST requests (webhooks) asynchronously with retry
  • Provides publish/subscribe interface using PubSubHubbub protocol (experimental)
  • Provides "Twitter Stream API"-style long-polling interface for topics (super experimental)


Hookah was originally created to ease the implementation of webhooks in your web systems. While webhooks are still at the core, it's becoming a scalable HTTP event engine with HTTP pubsub and long-polling event streaming. And of course, webhooks. Any system with webhooks or looking to implement webhooks will benefit from Hookah.


Hookah currently depends on Twisted.


Hookah is a simple, lightweight standalone web server that you run locally alongside your existing web stack. Starting it from the command line is simple:

    twistd hookah --port 8080

Using the Dispatcher

Posting to /dispatch with a _url POST parameter will queue that POST request for that URL and return immediately. This allows you to use Hookah as an outgoing request queue that handles retries, etc. Using HTTP means you can do this easily from any language using a familiar API.

Posting to /dispatch with a _topic POST parameter will broadcast that post to any callbacks subscribed to that topic (see following PubSub section), or any stream consumers with a long-running request on that topic.

Using PubSub

Refer to the PubSubHubbub spec, as Hookah is currently quite compliant with this excellent protocol. The hub endpoint is at /hub, but this multiplexes (based on 'hub.mode' param) between /publish for publish pings, and /subscribe for subscription requests.

This feature is still very early and as a result it is incomplete. The main caveat is that there is no permanent storage of subscription data or of the queues. This means if you were to restart Hookah, all subscriptions would have to be made again.

Using Streams

Hookah implements a long-running stream API, modeled after Twitter's Stream API. Just do a GET request to /stream with a topic parameter, and you'll get a persistent, chunked HTTP connection that will send you messages published to that topic as they come in. Refer to the Twitter Stream API docs to get a better feel for this pragmatic Comet streaming technique.


  1. Persistent storage (SQLite, MySQL, CouchDB) and queuing (in memory, Kestrel, RabbitMQ) backends
  2. Configuration
  3. Backlog/history with resend
  4. "Errback" webhook
  5. Async response handling


Hookah is released under the MIT license, which can be found in the LICENSE file.


  • you?


Jeff Lindsay

Learn more about web hooks