Skip navigation

Category Archives: Radar

MailChimp, an email marketing tool used by the likes of Firefox and Media Temple, recently announced the addition of web hooks to their API. Their primary use-case is to keep your email list in sync with theirs. They push to your callback URL with several types of events regarding list changes, including subscribes, unsubscribes, profile updates, cleaned addresses, and email changes.

Their API documention explains web hooks and how you use them with MailChimp. They also mention PostBin as an excellent utility to help see the event data as they’re triggered in their system.

Okay, it’s not really a dispute. That was sarcasm in the title. Just to be clear, since there’s always been a tiny bit of useful friction between the idea of XMPP and web hooks, it’s important to remember they are not mutually exclusive. Anybody hyping a battle between the two is trying to create or is imagining a controversy that isn’t real. Many proponents of web hooks are XMPP proponents as well. In fact, the video some are pushing around to promote this supposed throw down is of two XMPP supporters (including djabberd author Brad Fitzpatrick) demoing a pubsub system based on web hook callbacks. And it takes place at an XMPP meetup, so of course there was going to be some proselytizing.

Nevertheless, Jabber/XMPP is a messaging protocol. Web hooks provide a model for functional extensibility, so they are a platform for many different things. A push-based pubsub messaging system is just one use. Even though I originally wrote about web hooks as a notification mechanism, my mind was nowhere near pubsub. I was more focused on the idea of web service integration and orchestration. With the commoditization of CGI-enabled web hosting, I was thinking about how the popularity of web programming combined with the easy invocation of HTTP requests could be used to make a more useful and functionally extensible web. A more programmable web.

With that said, there is nothing wrong with discussing what you can and can’t do with web hooks and XMPP, but there is not some angry fight between camps. Done. Over. Moving on.

As it turns out, the project demoed in that video, which is called pubsubhubbub, is something I had previously stumbled upon while browsing projects a friend of mine was involved in. There wasn’t much of a description, and I didn’t dive too deep into the code, so I bookmarked it to come back to it. After that demo happened, it seemed I misheard (from several people) that it was some XMPP pubsub system, which totally confused me because… it’s not. It’s a neat, distributed pubsub implementation built on web hook callbacks created by Brad Fitzpatrick and Brett Slatkin (a Google App Engine developer). Hopefully they’ll put some more documentation up as it develops, but it’s just really neat to see some XMPP folks build an open pubsub system with web hooks. Cheers to them!

Timothy Fitz recently wrote on What webhooks are and why you should care. It’s a very clear and straightforward description of just that. It helps to have people other than me talking about web hooks. Granted, Timothy is a good friend of mine, but it did spark a good discussion in his comments and on reddit.

webhooks08_udell135Also, Jon Udell brought up web hooks in a recent post regarding Assembla’s usage of the model. It shouldn’t be a surprise that he considers the adoption of web hooks a game changer. I still quote him in my presentations for envisioning in 1997 “a new programming paradigm that takes the whole Internet as its platform.” It’s an idea I’m quite fond of that I believe requires more than web APIs.

While I’m at it, Joe Gregoria posted his initial reaction of web hooks last week. His major critique was the lack of rigorous text around the model. Certainly I write a decent amount about them, but I avoid specifics. My focus right now is sharing the big picture, getting people to implement them on their own, and documenting the different discoveries along the way. I personally don’t feel a need to try and standardize very much yet, but perhaps better specifics on “how to provide web hooks” would be a good thing to get documented.

I’m glad a wider discussion is starting to emerge. I’ve stumbled across several other blog posts on web hooks recently. Some of the issues people bring up are authentication, scalability, and reliability. I plan to cover these issues in upcoming posts since they’re pretty straightforward, but you’re all welcome to participate in this discussion. Feel free to join our discussion list, write a blog post, leave a comment, tell your friends, or best of all: try implementing the model yourselves.

Speaking of the discussion recently, it was pointed out that Uche Ogbuji started publicly thinking about this about the same time I did in 2006. He called them web triggers as inspired from the database world. I chose web hooks coming from the programming world. There are a lot of words that describe different aspects of the same pattern: events, signals, callbacks, hooks, triggers, handlers, listeners… I stuck with hooks not just to keep the name simple to pronounce and differentiable from common code-level event terminology, but I also liked the idea of “programmability” it implies.

Blaine Cook

It’s been a busy week for web hooks, eh? Well, I figured I might as well share a quick note I received while writing the Amazon post. Blaine Cook, former architect of Twitter, sent me a message after finding a post in which I said he was the one preventing Twitter from providing web hooks. You see, I gave my first public talk on web hooks at an event called SuperHappyDevHouse in 2007. Afterward, Alex Payne came up to me and said, “This is great, I’d love to put this in Twitter.” But it never happened, and I was under the impression Blaine was the one that shot the idea down.

Anyway, he sent me a message saying that although he thinks it’s unfeasible for Twitter to provide web hooks at their scale, he’s all for them in principle. In fact, he says his next project will have web hooks from the start, which is exciting to hear.

But I’m still not convinced Twitter is completely unable to provide web hooks. The fact they let you get all notifications via SMS means they’re either making a web request or at the very least, sending an email. Why can’t they asynchronously queue up the outgoing HTTP requests for users that want web hooks?

Anyway, the Twitter argument is for another time. I look forward to seeing what Blaine is up to and how he’s using web hooks.

Zendesk, the hosted help desk software, has had a feature called Targets. This allows you to send notifications to external destinations. I got really excited when I heard about this. Upon further investigation, I found that they are web hooks, but not necessarily the greatest example of web hooks.

Right now, they support two hard-coded targets: Twitter and Campfire. They also let you target an arbitrary URL, which of course they call “very powerful.” That’s a web hook, right? Yes, but unfortunately, the notification payload they send is a human readable text string. That’s not so bad, but really, code is going to process it, so why not make it more machine friendly?

My only other critique is that they shouldn’t hardcode the services they support for targets. They should do as GitHub has done and run a local web server serving open-source handler scripts. This way, they can allow others to easily write and contribute to Zendesk’s integration with other services and still support it and make it feel like hard-coded service integration.

I once had to build a shopping cart framework for a friend’s company in about three days. It was a challenge considering all the complexities involved in pretty much any instance of a shopping cart. Most shopping cart solutions would hardcode predefined rules or configurable options for determining tax, shipping, and promotional discounts. This was kind of ridiculous since those are usually the points where it varies quite a bit from cart to cart. My solution was to provide hooks because I knew these guys were programmers and were smart enough to implement their own callback functions to define whatever rules they wanted. It turned out to be very powerful, one of their favorite features of the framework, and it was trivial to implement.

So how does an architecture like that translate to a hosted e-commerce checkout solution? Obviously, web hooks! Amazon recently figured this out as they just announced a Callback API for their Checkout solution under their Amazon Payments arm. It lets people use their hosted “checkout solution” while letting them customize the rules for calculating taxes, shipping, and promotional discounts in the most powerful way: code.

This is a fairly significant example of web hooks because it breaks away from the notification use-case that people seem to be caught up with. By actually processing the results of a hook callback request, you’re opening up your application logic to the end user. This is user contributed logic, an under appreciated and mostly unrecognized trend for the emerging service platform aspect of the web.

I don’t want to tangent too much into a rant on the web I want (and I think we all want, but don’t realize it). Instead, I’ll summarize some details on this new Amazon announcement of web hooks. The full documentation for which can be downloaded in PDF format.

You define the callback endpoints in a configuration XML document used for setting up Checkout. They use HMAC authentication for hook requests with added timestamp nonsense, very similar to the way they do Amazon Web Services. The payload is somewhat surprisingly not XML, but instead a URL encoded key/value pair format. The strange thing is that they try and do nested data structures this way, which makes me think JSON would be the better choice. And just to confuse you slightly, in the documentation they use XML to describe the data structures they pass to you and expect back, even though XML is not actually involved. Nevertheless, the documentation is quite good.

Anyway, I’m happy to see a use-case emerge in a way that starts to hint at the aspect of this model I’m more interested in: customization via code. Notifications, or “push,” are really just something along the way. Although this is a trivial example, you should be able to start imagining how it could be used to build a plugin architecture for your web app. The ability to allow your users to extend and build new functionality they can share with others does not seem like an empty value proposition!

Until recently, I’ve only included Google in my list of companies that unintentionally provide an example of web hooks. Like PayPal’s IPN, Google Checkout provides a similar feature for notifications. However, I was recently informed that Google Code project hosting has a post-commit hook, which they’ve implemented explicitly using the “web hooks model.”

Google Code's Post Commit Hook

If you have a project hosted on Google Code, you’ll find this under Administer/Source. The documentation for this feature even links to our wiki. I had a feeling this would happen eventually with Google Code. This particular hook event is very popular with most project hosting services, including GitHub.

I never liked mentioning the Google Checkout Notification API because it was terribly heavyweight and didn’t seem to add much to the web hooks model. On the other hand, the Google Code post-commit hook is done quite exceptionally, and even shows a great method of authentication.

The Google Code hook payload is JSON, which is significantly more straightforward and simpler than XML. More interestingly, they use HMAC for authentication, which has been something of an unresolved issue with this model. HMAC seems quite suitable when authentication is necessary.

Like most of the cases of web hooks out there, this was done without my direct influence. However, separately I have been invited to give a private talk at Google on web hooks. That’s happening February 23rd and is open to anybody at Google. On top of this, Joshua Schachter recently joined Google and he’s been in the web hooks camp for a while, so I’m excited to see what else Google does with them.

Update: Google announced this feature on the Google Code Blog.

Today Gnip announced that they’re winding down XMPP support. Why? They say it’s not worth the work to support it right now. The XMPP world still lacks a leading server standard, leaving them to deal with a scattered array of various implementations. On top of this, many of their consumers are unwilling to deal with running their own XMPP server and end up using Google Talk or Jabber.org, which throttle throughput since they’re popular servers.

Web hooks don’t have these problems. This is probably why Gnip continues to use them as their primary mechanism for real-time push notifications. As ideal as XMPP sounds for real-time notifications, it lacks the simplicity and ubiquity of HTTP. Not only is it a new server implementation to worry about, it’s another type of server in the mix!

Anyway, this means I need to go back and edit my slides about Gnip. Despite this seeming like a victory for web hooks (when I contacted Jud Valeski about this, the Gnip CTO responded “Web hooks reigns!”), I was looking forward to Gnip providing a gateway between the world of web hooks and the world of XMPP. They’re likely to return to XMPP eventually, but this may be an opportunity for somebody to provide a focused XMPP to web hooks bridge.

As a sidenote, I’ve thought it interesting that Gnip is aware of “web hooks” as they use it in their diagrams, but their public use of the phrase has otherwise been lackluster. In their write-up of the announcement, ReadWriteWeb seems to have taken it upon themselves to call Gnip’s use of web hooks “Restful push.” Not bad. I’d probably call it that myself if it wasn’t about more than push. But that’s what the social media guys are into, and I don’t have a problem with that since social media is a trendy vehicle for web hooks.

I always try to point out that web hooks are nothing new. In fact, most “new” technology is not new. The mouse, for example: in 1984, when Apple introduced the Macintosh 128K, the mouse and GUI exploded in popularity and quickly became the standard model for interfacing with computers. Little did people know, the mouse had already been around for 21 years! It was invented at SRI by our pal Douglas Engelbart way back in 1963.

It’s interesting to note that the mouse is sort of useless without the GUI. The two are pretty strongly coupled. Perhaps the latent success of the mouse was in part due to the GUI taking about 20 years to be perfected and made ready for mainstream acceptance. In any case, most new technology is not new. Remember that, kids!

The name “web hooks” might be new, but the idea isn’t. The technology certainly isn’t; it’s just HTTP. In fact, you can say the same thing about REST, which wasn’t coined until 7 years after HTTP.

So what was the first major application of web hooks?


The classic example of a web hook is PayPal’s Instant Payment Notification feature, also known as IPN. This feature allows online retailers to handle real-time purchase confirmations from PayPal. After giving PayPal a URL for IPN, they perform an HTTP POST to it whenever the seller receives a payment. This allows the retailer to better integrate the rest of their system with PayPal.

It was a pragmatic solution to achieve simple server-to-server communication. What blows my mind is why it hasn’t been used for much more since then, hence this blog and my slight obsession with the idea. There have been others that have made use of this more recently, and I’m going to cover those guys on this blog, but still… IPN has been around for over 5 years.

I’m not sure how long PayPal has had the feature, but I know it dates back to at least 2003. And PayPal wasn’t the only one. There used to be (and still are) a lot of alternatives to PayPal which provide the same feature. Even Google Checkout has an IPN equivalent.

But the popularity and success of PayPal has given them loads of experience with IPN. They’re basically web hook veterans. I’d love to talk to some of their engineers about their experience providing the IPN feature. How it evolved, maybe how it scales, how the community likes using it, what kinds of tools have been made around it…

Actually, one thing I didn’t realize until I researched it for this post, is that there are 3rd party services that consume the IPN web hook to provide extra features for the retailer. For example, Scrobbld extends the functionality of PayPal with a nice web UI to manage post-sale affairs without even entering your PayPal username. It’s based entirely on consuming the PayPal IPN.

Now an interesting thing to note about PayPal’s implementation of IPN is their confirmation step. Instead of just sending the IPN in a fire-and-forget fashion, they want you to perform an HTTP POST back to them with all the data from the IPN. They use this to prevent spoofing and let you know the IPN did, in fact, come from them.

The HTTP status code you respond to the IPN with is used to determine if they should resend the notification. If you return anything other than 200 OK, they try to resend the IPN in full for up to four days.

And although some people like the idea of a structured payload document in their web hook posts, PayPal IPN data is straight up simple key/value request parameters. This eliminates the need for the consuming script to parse anything beyond what their CGI library probably already takes care of. In the case of PHP, all the data is right there in $_POST.

So in general, I like PayPal’s approach to IPN. They’ve had plenty of time to get it right and do a good job at keeping it simple. Although they might not be the very first example, they’re definitely the most used example of web hooks in action.

Now, I was just thinking about the mouse and GUI analogy I made at the beginning here. Web hooks are a complement to web API’s in much the same way the mouse is a complement to the GUI. In fact, like the mouse, without their API counterpart, I think web hooks are much less useful. Without a GUI, how useful is a mouse?

Perhaps the reason web hooks are taking longer to be adopted is similar to the mouse waiting for the GUI to develop. Even though IPN was around in 2003, it wasn’t until 2005 that web API’s started to become popular. Now that API’s are pretty commonplace, I guess it makes sense web hooks are starting to grow in popularity…