Getting Started with PubSubHubbub

To my knowledge, Superfeedr is the only non-google PubSubHubbub out there. Let’s see why and how to use it.

Why using PubSubHubbub?

Superfeedr provides 2 API. Here are some reasons why you’d be better off using the PubSubHubbub API:

• You don’t want to run a background job
• You have an existing Web application
• You already use PubSubHubbub with another hub.

And here are a few reasons why you may want to avoid the PubSubHubbub API.

• Your endpoint (where you will receive notifications) is *behind a firewall
• You want to receive a notification each time Superfeedr fetches and parses a feed for you
• Your endpoint(s) are either desktop applications or embedded applications

What do I need to do?

The PubSubHubbub API will allow you to receive notifications from us when we identify new entries in feeds to which you subscribed. Thus, there are 2 things that you need to do : subscribe and implement a “receiver” to deal with notifications.

Subscription

The subscription process is not obvious, because the hub needs to verify your intent. Here is how it works.
Our hub is located at http://push.superfeedr.com/

1. Send an authenticated (with your superfeedr login/password) POST request to our URL with the following parameters :
   – hub.mode = subscribe|unsubscribe
   – hub.verify = sync
   – hub.callback = http://domain.tld/your/callback
   – hub.topic = http//feeds.you.want.to/subscribe
2. When our server receives this POST request, it will send back a GET request to your callback URL, with the following :
   – hub.mode = subscribe|unsubscribe
   – hub.topic = http//feeds.you.want.to/subscribe
   – hub.challenge = a-random-string
3. If your server echoes the hub.challenge parameter (along with a 200 response), the subscription will be accepted. It will be refused in any other case.

To debug the process, you can use this hurl to send subscriptions requests (don’t forget to adjust the values of the params, though). Curl is another great option.

Receive Notifications

Your application must “deal” with the notifications. Notifications are POST requests sent to you callback URL, the new entries are in the request body. You then have to use an XML parser to fetch that body. Since we use standard ATOM, any parser that can deal with ATOM will be great.

If you’re using a web application framework like Rails, Django, Merb or Symfony, it should be quite easy to register a “route” connected to the right Controller, in charge of parsing this body.

Existing libraries and plugins

The great advantage about using a standard protocol, is that you can re-use any “code” that’s been written for other hubs. Here is a small list of existing libraries that can help you deal with the subscriptions and handling notification from your web app. That should all be fairly easy to implement.

• Empika’s Rails plugin
• Django App
• Ilya’s EventMachine Ruby daemon
• PHP subscriber Client
• Zend Subscriber
• Haskell Client
• Python Subscriber
  …

You can also find several PubSubHubbub repositories on github, some of them claim to implement the subscriber part of the protocol.

Finally, please take the time to read our PubSubHubbub documentation as this blog post is just a “getting started” guide.