Friday, February 24th, 2012

Box Webhooks Beta

By

I’ve always been fascinated with integrating systems together that weren’t exactly designed to go together in their original format.  One of the best ways you can integrate disparate systems, at least in my experience, is to use an automated notification from one system to another.  Enterprise systems at large companies are laced with notifications; pager alerts for hardware failures or automated backups that kickoff when backup batteries kick in.

But why not automate notification for when Bob down in accounting pulls up your expense report, or maybe just when he edits it and re-saves it.  Wouldn’t it be great if uploading that status report to the team folder triggered an email for your team to check it out?

That’s what Box webhooks are all about. Today, we’re launching them in beta, so you can get started – expect a full launch in the near future. For now, if you want to try them, just email us at developers@box.com.

This article will walk you through creating your own webhook program in Node.js.   Add in the magic of Heroku’s hosting of Node.js, and you’ve got an instant application.

Updates and webhooks

The webhook system is based on Box’s updates stream, which also powers the updates tab on our website.   When you setup your own webhook, you can decide which events you want to have trigger your webhook.   Our updates tab is all pre-configured for you, so it’s not nearly as flexible.

Getting started

First, I created a Box application, then I set up a Heroku account – of course, if you prefer, you could use some other server that you have out on the internet.   If you haven’t tried Node.js, you should read a quick tutorial on that – I recommend http://www.nodebeginner.org/.  A quick confession:  This is the first Node.js I’ve written, so it’s obviously not that fancy, and not that hard, either.

Then I created the sidebar’d Node.js program on your Heroku account.  See Heroku’s instructions for how to deploy it (an extra couple files to tell Heroku where your program is, and following their git instructions to get your code up there).

var http = require('http');
var url = require('url');
var port = process.env.PORT || 3000;
var logs=[];
var server = http.createServer(function(req, res){
	res.writeHead(200, {'Content-Type': 'text/plain'});

	if (req.url == "/log"){
                for (var i=0; i<logs.length; i++){
                   res.write(logs[i]);
                   res.write('\n');
                }
		console.log('Printing logs');
	} else {
		var query = url.parse(req.url).query
		if (query != undefined){
			console.log('Got a query for %s', query);
                            logs.push(query);
			    logs.push('\n');
		}
		res.end('ok');
	}
});
server.listen(port);
console.log('server running at %s', port);

This Node.js program has two types of callers.  Any caller to /log must be a log listener.  They are added to the array of log listeners.  All other requests are responded to with an “ok” and echoed to the log listeners.  It’s nothing fancy, but if you point two browsers at it, you can see how it works.

http://<yourHerokuURL>/logs

http://<yourHerokuURL>?param=value

The first browser will sit there and do basically nothing, with a spinning icon showing that it is waiting for some input.  The second browser will respond with an “ok.”    As it responds with the “ok” it will send the “param=value” section of the 2nd browsers URL over to the /log browser.  Viola, you’ve got a logger.  Y, it’s ugly, and it doesn’t really close out the session, or make pretty HTML, but you can see all the various HTML calls to your little application.

Hooking up webhooks

So now it is time to create a Box webhook.   I’m interested in people previewing, downloading my documents, updating them, or adding comments, so I check the appropriate boxes in my app editing screen on http://box.com/developers/services, and then paste in my URL for my Heroku app.   Finally, I pick a few parameters that I’m going to want to use on the other end to make my log entry more meaningful.

Then I install my application on my Box account, and that’s it: ready to go.   Now I can go back to my http://webhookslogger.herokuapp.com/log, and watch the changes to my documents trigger logging entries.

What’s next?   How about sending emails about these updates instead of just logging them to some HTML page?   Come see my demo at CloudStock 2012, and I’ll show how that would look. If you want to get started with webhooks before then, shoot us an email at developers@box.com, and we’ll get you set up.

By

See all of Peter's articles.