Skip to content


Subversion checkout URL

You can clone with
Download ZIP
a distributed EventEmitter and i/o framework for node.js

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


 __    __    ______     ______    __  ___         __    ______   
|  |  |  |  /  __  \   /  __  \  |  |/  /        |  |  /  __  \  
|  |__|  | |  |  |  | |  |  |  | |  '  /         |  | |  |  |  | 
|   __   | |  |  |  | |  |  |  | |    <          |  | |  |  |  | 
|  |  |  | |  `--'  | |  `--'  | |  .  \    __   |  | |  `--'  | 
|__|  |__|  \______/   \______/  |__|\__\  (__)  |__|  \______/  

the node.js web hook platform (aka yahoo crack pipes)

Current Status :


v0.1 is almost out (i swear!) protocols : 10 webhooks listeners : 3 webhook actions: 4

the webhook book (TWHB)

Table of Contents

  1. what is a webhook

  2. what is a webhook listener

  3. what is a webhook action

  4. what is

  5. installing

  6. putting a front-end on

  7. the api

  8. using the JSON-RPC api gateway

  9. creating custom webhook listener and action definitions

  10. creating custom protocols

TL;DR - low attention span? go here => installing hookIO

overview is a open-source web hook platform built entirely in JavaScript and node.js. it is both a free open-source project and a free software as a service provided at's dual model is unique in that it allows developers and businesses the choice of using as a third party web-service or downloading and installing their own copy of and doing whatever they want with it, without limitation.

everything in is standardized, modular, evented and enumerable. we love standards and leverage the CommonJS module system for extending and customizing is heavily linked with the node.js project and NYC.js, we share a few developers.

what is a webhook platform?

a webhook platform is an application platform for automating simple actions to take place on arbitrary web events. a webhook platform can concurrently listen for millions of poll or push events and execute actions which are bound to these events.

what is a webhook?

a webhook listens for some stuff to happen and then when that happens it does some other stuff

what is a webhook listener?

the listener of a webhook is the event that needs to get triggered in order to execute the webhook's actions. for now, we will focus on three basic types of listeners.

timer listeners

often a webhook listener will be based on a timer. the webhook will poll a resource on a set interval looking for a response. once the resource responds the webhook will execute its actions and pass along the payload received from the resource

HTTP listeners

a webhook listener can also be implemented as a unique URL. any HTTP request performed on this unique URL will trigger the webhook, passing along the incoming HTTP request's payload to the webhook's actions

socket listeners

perhaps one of the most powerful listeners, a socket listener will open up a socket with a resource and wait for that resource to push a response to the webhook. when the response is received it is passed along to the webhook's actions as they execute.

what is a webhook action?

the action of a webhook are the events that will executed once that webhook's listener is triggered.

what type of actions can a webhook have?

this is where things get interesting. the actual actions of a webhook are completely arbitrary. most of the time a webhook's action will be performing an outgoing HTTP request, but with access to custom protocols you can perform almost any action

many actions, one webhook

a webhook may contain more then one action. there may be many actions attached to one listener. often, you will attach several actions to one webhook.

chaining webhooks

a webhook's action may also point directly to another webhook. this essentially short circuits the webhooks listener and forces execution of the webhook. this means you can link webhooks together, passing along your payload from webhook to webhook and creating a chain of complex functionality

what is is an open-source webhook platform built entirely in JavaScript and node.js. it is both a free open-source project and a free software as a service provided at as a software as a service

if you want to try without installing anything you can visit and use the web interface. you can also integrate your application with's JSON-RPC webservice located @ as stand-alone server

if you want to run on your own hardware you can easily git clone the github repository and start your own instance. this instance is completely autonomous and doesn't communicate with any outside services unless you tell it to. as a CommonJS module is a valid, self contained, CommonJS module. this means you can import the module into an existing node.js application. once imported, you can seamlessly call methods through the api object which is exported as "hookIO.api" has no front-end is completely decoupled from any front-end. this is very powerful in that it allows developers to easily create customized front-ends or widgets in the technology stack of their choice

we provide a sample front-end which powers, you can clone it @

we also provide a brower-side jQuery/JavaScript api for communicating with's JSON-RPC

JSONP support is coming soon.

how does store data? can work with Mongo, Redis, Couch, MySQL, and SQLlite, but comes embedded with node-dirty so you can persist data instantly without any third-party software. this means as soon as you start you have a database.



  1. node.js


$ git clone
$ cd
$ git submodule update --init as a standalone server

$ node server.js

this will start a instance on port 8000 of your machine. as a CommonJS module

var hookIO = require('./');

putting a front-end on is completely decoupled from any front-end. this is very powerful in that it allows developers to easily create customized front-ends or widgets in the technology stack of their choice

getting started

if you want to put a quick front-end on you should clone the

just serve the front-end site as static html on the same host where you are running

creating a custom front-end / widget provide's a brower-side jQuery/JavaScript api for communicating with's JSON-RPC

you can import this one JS file into your existing front-end site and easily all's api methods.

setting up and nginx

nginx is an ideal choice for serving a front-end for

use this nginx.conf file serve the and reverse proxy pass JSON-RPC requests to the running instance

the api

the api is the primary interface for interacting with


at it's most basic level you can interact with api through CommonJS. can expose it's api over arbitrary gateways allowing easy integration other applications.

what are's web hook and action definitions?

a web hook consists of an arbitrary listener and at least one arbitrary action. implements a hook dispatcher and an action dispatcher. the dispatchers validate configurations and delegate events to where they belong.

custom hook and action definitions might contain some of your business logic, but really they are meant only for routing purposes. if you need to define re-usable logic that can be spread across many definitions you will want to implement a protocol.

a "protocol" in it's simplest form is a CommonJS module. you can create a protocol that does anything. check out our current protocols and node.js

what would you build a protocol for?

really anything. if you wanted to integrate with Flickr, you would create the Flick.js protocol. now every single api method for Flickr can be called from a hook definition or an action definition.

Something went wrong with that request. Please try again.