Document WebHooks

README.md

@@ -164,6 +164,71 @@ pusher.get({ path: '/channels/[channel_name]/users' }, callback);
 
 The `channel_name` in the path must be a [presence channel](http://pusher.com/docs/presence). The structure of the returned JSON is defined in the [REST API reference](http://pusher.com/docs/rest_api#method-get-users).
 
+### WebHooks
+
+The library provides a simple helper for WebHooks, which can be accessed via Pusher objects:
+
+```javascript
+var webhook = pusher.webhook(request);
+```
+
+Requests must expose following fields:
+- headers - object with request headers indexed by lowercase header names
+- rawBody - string with the WebHook request body
+
+Since neither Node.js nor express provide the body in the request, your application needs to read it and assign to the request object. See examples/webhook_endpoint.js for a simple webhook endpoint implementation using the express framework.
+
+Headers object must contain following headers:
+- x-pusher-key - application key, sent by Pusher
+- x-pusher-signature - WebHook signature, generated by Pusher
+- content-type - must be set to application/json, what Pusher does
+
+After instantiating the WebHook object, you can use its following methods:
+
+#### isValid
+
+Validates the signature of the WebHook and returns a boolean. Your application should validate incoming webhooks,
+otherwise they could be faked.
+
+Accepts an optional parameter containing additional application tokens (useful e.g. during migrations):
+
+```javascript
+var webhook = pusher.webhook(request);
+// will check only the key and secret assigned to the pusher object:
+webhook.isValid();
+// will also check two additional tokens:
+webhook.isValid([{ key: "x1", secret: "y1" }, { key: "x2", secret: "y2" }]);
+```
+
+#### getData
+
+Returns the parsed WebHook body. Throws an error if the content type is not `application/json` or the body is not valid JSON.
+
+```javascript
+// will return an object with the WebHook data
+webhook.getData();
+```
+
+Please read [the WebHooks documentation](http://pusher.com/docs/webhooks) to find out what fields are included in the body.
+
+#### getEvents
+
+Returns events included in the WebHook as an array. Throws errors the same way as `getData`.
+
+```javascript
+// will return an array with the events
+webhook.getEvents();
+```
+
+#### getTime
+
+Returns the Date object for the time when the WebHook was sent from Pusher. Throws errors the same way as `getData`.
+
+```javascript
+// will return a Date object
+webhook.getTime();
+```
+
 ## Tests
 
 The tests run using [Mocha](http://visionmedia.github.io/mocha/). Make sure

examples/webhook_endpoint.js

@@ -0,0 +1,30 @@
+var express = require("express");
+var Pusher = require("../lib/pusher");
+
+// provide auth details via the PUSHER_URL environment variable
+var pusher = new Pusher({ url: process.env["PUSHER_URL"]});
+
+var app = express();
+app.use(function(req, res, next) {
+  req.rawBody = "";
+  req.setEncoding("utf8");
+
+  req.on("data", function(chunk) {
+    req.rawBody += chunk;
+  });
+
+  req.on("end", function() {
+    next();
+  });
+});
+
+app.post("/webhook", function(req, res){
+  var webhook = pusher.webhook(req);
+  console.log("data:", webhook.getData());
+  console.log("events:", webhook.getEvents());
+  console.log("time:", webhook.getTime());
+  console.log("valid:", webhook.isValid());
+  res.send("OK");
+});
+
+app.listen(3000);

package.json

@@ -28,7 +28,8 @@
     "mocha": "=1.20.1",
     "expect.js": "=0.3.1",
     "sinon": "=1.10.2",
-    "nock": "=0.36.2"
+    "nock": "=0.36.2",
+    "express": "=4.4.3"
   },
   "keywords": ["pusher", "websockets", "realtime"],
   "repository": "git://github.com/pusher/pusher-node-server",