Webhooks First Steps

I attended Barcamp Miami on Feb 22.  It was excellent.  I gave a talk on Webhooks which was well received.  In the following days, I got to thinking about next steps.  Before I go into that, it makes sense to give a little background.

In a simplistic sense, Webhooks can be viewed as a design pattern where one application can notify another application about some event.  A typical use case would be an application or service that wanted to notify a user for some reason.  Instead of sending an email to the user, the application would push the message to a URL that the user provided.  Sitting at that URL is some code that the user has designated as the recipient of the message.  That code can do whatever the user wants.  The key, is that the message passing mechanism becomes a programmable one.  If that user wants to get an email, he can do so.  However, he can do just about anything he wants with it.

Webhooks are also envisioned as HTTP calls.  The idea is to have a simplistic mechanism that can be easily implemented.  We envision that the impact of this can be wide reaching.  However, if such a mechanism were widely implemented it is not possible to predict what the results will be.  Such things tend to defy prediction and anyone who tells you they know what would happen may have some idea, but they will most likely be proved wrong or shortsighted.

I fell asleep one night thinking about implementing a simple Webhook library in PHP.  I figured I had to create a server and a client component.  And it should be done so that whoever used the library could drop in these components and voila, they would have a communication channel.  Next I started thinking about what data I would want to push.  It would be easy enough to just push the message.  But we would probably want some other meta data just for house keeping purposes.  Here is what I would want to start with:

• Date and time the message was generated
• Name of application that generated the message
• Some event tag indicating what event occurred
• Who the message is targeted to (user id, user name, email )
• Message

These should be sufficient to get something going.

I’m thinking that I will encode the data in JSON.  Why JSON you ask?  I’d ask why not.  We need something.  This would make it easier to make a Javascript library.

This would be an example of a project management application giving notice that a task has been completed.

{”webhook” : {
“datetime” : “20090225001025″,
“application” : “mygreatproj.com”,
“event” : {”id” : “task-completed”, “project”:”name-of-proj”, “task” : “102-shipment delivered” } ,
“to” : “ryantxr”,
“message” : “the message would go here.” }}

Notice that I put in specialized information that is specific to the type of event.  This example is about project management.  We could have just embedded this information into the message body.  At this point,  I am choosing not to do this.

The next step will be to write some code.  I will have to get to that later.