A Fast Introduction to Hookbox

by Michael CarterJuly 26th, 2010

Hookbox is the web-push server that integrates directly with PHP, Django, Rails, Java servlets, ASP.Net, and any other HTTP-based application framework. Hookbox is Open Source Software under the MIT License. This visual tutorial is ten simple steps that give you a basic idea of Hookbox’s capabilities. It will only take you a few minutes to work through, and no installation is required!


You can install Hookbox manually, but a much faster way to get started is to create a Hosted Hookbox account. Hosted Hookbox is absolutely free; it is intended for developers to try Hookbox out without investing substantial time and energy. Just remember that you should not run production apps on Hosted Hookbox as it is meant primarily for testing purposes.

Diving in

  1. Navigate to the Hosted Hookbox Signup Page and create an account.

  2. Choose and enter an admin password for your Hookbox instance. Click ‘Save & Restart’.

  3. Navigate to the Admin Menu option in a new tab and enter the admin password you just chose.

  4. Now you should see the admin panel. Feel free to explore and see what’s available. There isn’t much going on here yet, but there will be soon.

  5. At this point you’ve deployed a Hookbox instance and logged into the admin panel. Now we need to try logging in some users. Back in your Hosted Hookbox account page, you should see a ‘Client Test Utility’ link. Open this link in two new browser windows.

  6. In both Test Client windows, click connect with the given url (it should automatically populate the field with the url for your Hosted Hookbox instance.)

  7. In each tab, once the client is connected, type test_channel into the Channels name field and click subscribe. Each tab will automatically be assigned a random username when they connect (more on this later).

  8. Now you can publish messages back and forth between the two connected clients. Go ahead and open up multiple Test Client instances, and feel free to use multiple browsers/machines. You’ll be able to see the list of connected clients in the Presence section, and all channel events (publish, subscribe, unsubscribe) in the History section.

  9. Open up the tab where you are logged into the admin panel. Select Channels and then click test_channel.

  10. This view allows you to monitor and administer the channel. Here you can modify channel options, remove users, publish messages, or simply watch.

    Try publishing a message from the admin panel and watch it appear in the Test Client pages immediately.

What about my web app?

This ten step tutorial shows how a client can interact with Hookbox. Adding web app integration is also trivial; in fact, the demo you just played with is integrated with a Django application. In particular, you’ll notice the “Simple Callback URL” field in the Hosted Hookbox account page. Anytime Hookbox sees an event such as someone connecting, subscribing, or publishing, it sends an HTTP request to that callback URL asking for permission for the action. The web application hosted at that callback URL is passed various parameters in the form, such as the type of action, the channel_name, the user name, or the payload.

You can actually see exactly what the default callback URL does. For instance, when you connect from the Test Client page, Hookbox sends a connect callback to the URL: http://hosted.hookbox.org/test_callback?action=connect. If you open this URL in a new tab, you’ll see a response like:

[true, {"name": "qihagi"}]

This is where those random user names come from. Hookbox does not generate the usernames; rather, the web app — powered by Django in this case — provides the name for each user that connects to Hookbox. In a production application, we would have used Django’s sessions to determine the username and authorize the connection.

Try http://hosted.hookbox.org/test_callback?action=create_channel& channel_name=test_channel to see how the web application authorizes Hookbox to create a channel. You should see a response like:

[ true, { "history_size": 20, "reflective": true, "presenceful": true } ]

You can see a log of all interactions between Hookbox and your web application by opening the Webhook Logs section of the admin panel

Additionally, the web app can interact with Hookbox via the REST API. Navigate back to the Hosted Hookbox screen, enter a Rest Secret, and click Save & Restart. The Test Client and admin panel do not automatically reconnect, so you’ll have to refresh/reconnect the window(s) running the Test Client and re-login to the admin panel. The Rest Secret is a token shared between the web application and Hookbox; it is passed in the querystring of any REST call to Hookbox. Lets try one. Assuming my Hosted Hookbox name is “mcarter5″, and my rest secret is “abc”, then I can publish to test_channel by requesting the following URL:

http://mcarter5.hosted.hookbox.org/rest/publish?payload="hello from REST"&channel_name=test_channel&secret=abc

Go ahead and alter the url to fit your username and secret rest key and try it out. It will publish the message to your test clients, and you should see a response like:

[ true, {} ]

Another REST call to try is get_channel_info:


You should see a response like:

            "form":{ }
         "state":{ },
            [ "SUBSCRIBE", {

You can find more information about these calls at the Hookbox REST Documentation.

JavaScript integration

To use Hookbox with your app, you need to include hookbox.js. It is served from your running Hookbox server at /static/hookbox.js (or hookbox.min.js,) but you can also download it and serve it from your web app if you like. For example, my hookbox.min.js is served at http://mcarter5.hosted.hookbox.org/static/hookbox.min.js. The API provided by hookbox.js is straightfoward: There are methods to connect, subscribe, unsubscribe, publish, and disconnect. There are callbacks for when other users perform these actions. You can read more about this from the Hookbox JavaScript Documention.


Hookbox can be used to create all manner of real-time web apps. It is particularly well suited to the following:

  • Chat (presence, rooms, history, and the whole nine yards)
  • Stock feeds
  • Real-time data monitoring graphs / feeds
  • Multiplayer taking-turns-style games (cards, chess, trivia, backgammon, etc.)
  • Real-time administration / monitoring panels
  • Push-notified blog comments

The Webhook callback and REST interface allows you to use absolutely any HTTP-based application framework/language. You don’t have to learn a new way of writing applications just to make them real-time. Simply design a web application as you normally would, and then use the Hookbox APIs to integrate real-time features!

15 Responses to “A Fast Introduction to Hookbox”

  1. Orbited Blog » Blog Archive » Introducing Hookbox Says:

    [...] take a look at A Fast Introduction to Hookbox, an article/tutorial that I just published on Comet Daily. I hope that you’ll find the [...]

  2. pablop Says:

    Does it works across domains?
    Do you use long polling, forever frame, websockets or something else?

  3. Michael Carter Says:

    Hookbox works fully cross-domain. It uses WebSocket when it is available, and falls back on Comet Session Protocol otherwise.

  4. Salman Says:

    I tried the hosted example using two browser sessions (Firefox 3.6.7 and Chrome 6.0.472.0 dev). Firebug reported that the CSP protocol was being used by Firefox (which is expected because that version of the browser does not have web socket support). However, the version of Chrome I used does have websocket support (http://jwebsocket.org/index.htm?page=browsers.htm) and it still default to using CSP rather than websockets. Is this a bug?

    Other than that, the chat demo worked flawlessly.

  5. Lance Says:

    Hi Michael,

    Thanks for the post and effort on the hosted testing.

    I can say I have done some testing on hookbox with it installed on my own server and it looks great! It took about 5 min. and had the chat example working in 10. It’s the simplest setup of all the comet I have tried. Also appreciated the PHP examples and hooks.


  6. Durairaj Athavan Raja Says:


  7. Michael Carter Says:

    @Salman, nice work checking into WebSocket support; you’re right about chrome 6 using CSP. This is because hosted Hookbox is running behind nginx which will not proxy the WebSocket handshake properly, so Hookbox falls back to CSP.

    If you were to deploy your own Hookbox server directly, then WebSocket would work.

  8. A Simple Experiment with Hookbox Says:

    [...] While still in its infancy, Hookbox looks like a very promising project. From a developer’s perspective, it allows you to get something up and running very quickly. Its simplicity derives from the web hook api which also concerns me a bit. Using HTTP for inter-process communication, as in my example producer.py communicates with the hookbox server to publish data, doesn’t seem like the best choice for low-latency high-throughput applications. Perhaps Hookbox might introduce a web socket interface for inter-process communication so that the data can travel from the producer to the consumer using only one protocol? Overall, I’m quite impressed with Hookbox and really hope that it gains momentum. And lastly, don’t forget to read Michael Carter’s introduction to the project on cometdaily.com! [...]

  9. Sten Gruener Says:

    I am sorry, but I miss the installation guide. Can some one help me to deploy hookbox on my own server?

  10. MichaelCarter Says:

    @Sten, from the article: “You can install Hookbox manually

  11. Aris Samad Says:

    I’ve been testing Hookbox for about 2 weeks now and it rocks! Here is a log of my experiences: http://arissamad.wordpress.com/2010/08/16/hookbox-is-the-fastest-way-to-add-comet-functionality-in-an-existing-webapp/

  12. Jette Nielsen Says:

    I am missing Hookbox here: http://cometdaily.com/maturity.html

  13. E Says:

    Looks like hookbox is dead. Site returns 404.
    No docs. Latest commit in (https://github.com/mcarter/hookbox) at Nov 2010.

  14. Jamesjacob Says:


    This is great work. I want to use hookbox to build chat application in my website. Here i am unable to publish message to one particular subscriber in channel. I am newbie to hookbox, please guide me how can one subscriber communicate to other subscriber in one channel?

  15. noutati jocuri Says:

    I found APE easier to deploy and with a better set of features. I needed it for a php web-app, so it was a good choice. Still looking to see what the downsides are, as I am quite new to comet.

Copyright 2015 Comet Daily, LLC. All Rights Reserved