This article is a stub. You can help the IndieWebCamp wiki by expanding it.
PubSubHubbub (PuSH) is a notification-based protocol for publishing and subscribing to feeds/streams in real time. Currently there are no known indieweb sites that subscribe to anything using PuSH.
You should implement PuSH for your home page updates so that IndieWeb readers (like shrewdness) can:
- promptly receive your posts when you publish them
- and avoid polling your server with unnecessary traffic
There are several indieweb sites producing PuSH notifications, and a few indieweb-centric applications that consume them (see in particular indie readers, Shrewdness and Woodwind).
Tantek Çelik uses Falcon to send PuSH notifications of each post in his tantek.com Atom feed file since 2010-02-01.
Aaron Parecki uses p3k to send PuSH notifications for each item in his aaronparecki.com notes and articles Atom feed files since ????-??-?? (at least 2014-??-??).
Bret Comnes sends PuSH notifications for his bret.io Github Pages/Jekyll Atom feed file since 2014-03-16.
Kyle Mahan uses Red Wind to send PuSH notifications for new/edited posts and new mentions in his kylewm.com Atom feed file since 2014-03-23
- Now also sending notifications for updates to the main h-feed at kylewm.com, using a hub at superfeedr.com. Confirmed working 2015-02-21.
Barnaby Walters uses Taproot to send PuSH notifications for each new post on his WaterPigs.co.uk homepage HTML feed using PuSH 0.4 and Google’s hub since 2014-03-25.
David Shanske uses WordPress and the PushPress plugin to send PuSH notifications since 2014-02-16.
Matthias Pfefferle uses WordPress and the PubSubHubbub Plugin (selfdogfooding) to send PuSH notifications since 2011-01-29.
Note: This section is largely redundant with How_to_publish_and_consume_PubSubHubbub.
Publish a PuSH-enabled feed
PuSH 0.3 supported push notifications only for XML feeds, PuSH 0.4 generalizes this to allow publishers to send push notifications for any HTTP resource (e.g. h-feeds). If in doubt, use the newer spec, 0.4.
Publish PuSH 0.4
Since version 0.4 it is possible to push arbitrary content like HTML+microformats, or even JSON. The full spec for publishers is pretty small and readable.
Advertise PuSH Hub and Topic
To push HTML posts/comments or other HTTP resources, you must give potential consumers two pieces of information: the hub that you send pings to and the topic, typically just the URL of the resource.
- The PuSH spec requires resources to serve two HTTP Link headers rel=self and rel=hub.
- Check that you are serving the appropriate link headers by fetching your site with
curl -I [url]
kmahan@lemur:~$ curl -I https://kylewm.com
HTTP/1.1 200 OK
Date: Thu, 26 Feb 2015 04:44:06 GMT
Content-Type: text/html; charset=utf-8
Note: typically you can set Link headers from your application OR in your webserver (apache/nginx) configuration.
Note also: the spec allows consumers to fallback on alternative methods for finding rel=hub and rel=self, e.g. searching the HTML body for link elements like <link rel="self" href="https://kylewm.com/">. Superfeedr does not currently support link elements in HTML, but User:ouvre-boite.com said they may add support in the future.
Notify Your PuSH Hub When Your Feed Updates
When you post an update to your feed, send a POST message to your PuSH hub, telling it which resource has updated. Strangely, this mechanism is left unspecified, and is generally at the hub's discretion. Here is Superfeedr's mechanism:
For other hubs, refer to their documentation.
Publish PuSH 0.3
To publish PuSH 0.3 you need to do three things
- Pick a hub to push your notifications to, e.g. one of these
- Setup discovery of your Atom feed and hub
- home page
<link rel="alternate"> to your Atom feed.
- home page+Atom feed
<link rel="hub"> to your hub.
- Notify the hub
How to PuSH from WordPress
There is a plugin called "PushPress" which you can install on your self-hosted WordPress install.
An alternative, that also supports PubSubHubbub v0.4, is the PubSubHubbub Plugin.
If you're using WordPress.com, they already support PuSH by default (likely using that plugin).
Subscribe to a PuSH-enabled feed
- detect the hub for the feed, optionally falling back to a polling hub (like Superfeedr) if none is found
- send a subscription request to the hub for that URL, with a callback URL for the hub to ping with new content
- respond correctly to the verification of intent
- receive new content from the feed, POSTed straight to the callback URL
Hub discovery algorithm as described by julien51 :
- Find resource you want to subscribe
- Check for a "Link" header which points to a hub.
- If there is one => Subscribe to the hub designated
- If there is none, continue
- Check for a linking element (
link) with rel~=hub
- If there is one, subscribe using the designated hub
- Otherwise, continue
- Check for a <atom:link> element which points to a hub.
- if there is one => Subscribe to the designated hub
- If there is none => Subscribe using the Superfeedr default hub : push.superfeedr.com
Also, along with the hub link (both in the HTTP headers or the ATOM/RSS), you should check for a self link and use this one as the hub.topic you want to subscribe.
The Superfeedr documentation has a more detailed guide: http://documentation.superfeedr.com/subscribers.html
This application http://push-pub.appspot.com/ is a useful tool for testing your subscriber (subscribe to it and then create new posts, and see if the show up in your subscriber implementation)
Subscribing to Fragments
Superfeedr also offers the unique ability to subscribe to fragments on a page, using the # symbol. For example, if you subscribe to http://tantek.com/#.hentry, you will receive POST to your webhook/callback endpoint with the content of the first element of class "hentry" on http://tantek.com/
This should be seen as an optimization. A minimal consumer can simply re-fetch the resource itself when it receives a ping.
Testing your PuSH-enabled feed
There are several ways you can test whether or not your PuSH feed and pings are working properly:
Most popular RSS Readers do implement PubSubHubbub, you can just subscribe to your feed on one of them, and see if the update as been propagated after you added content.
- subscribe to your home page from a Status.net account
- publish stuff on your home page
- see updates appear in real time on your Status.net account
There are several XMPP/IRC bots which allow you to subscribe to feeds and be notified of updates via any XMPP or IRC client. You’ll need an XMPP account, or an IRC client.
Notifix is a bot (see above for source code). It's constantly connected to irc.freenode.net. Send him a private message like +help to see available commands. Subscribe with +subscribe <feed>, publish your content and see if you get the ping straight via IRC.
- I have had better experiences with notifixlite than PuSH Bot --Waterpigs.co.uk 03:16, 5 June 2013 (PDT)
- You can also register with Superfeedr to get your own subdomain (e.g. https://kylewm.superfeedr.com). This gives you access to useful stats like number of subscribers and notifications.
- As far as I have been able to tell, development on this hub completely halted in 2011, and it was left in a weird state. Appears to partially support non-XML feeds but for example requires hub.verify (a parameter that was removed in 0.4). For new development and for all h-feeds I strongly recommend not using this hub. Kylewm.com 13:55, 28 February 2015 (PST)
The following implementations consume and subscribe to PuSH feeds:
- There are only 3 hosted hubs according to this list of which the one run by Google looks like a side-project (and I suspect it does not offer any service level guarantees) and I haven't heard much about Ayup. Which essentially means there is only one hosted hub to speak. Hubs are complex by design and therefore not something indieweb people can/should run themselves. This is not a healthy situation for something to be considered as indieweb infrastructure -Www.sandeep.io 06:09, 3 July 2013 (PDT)
- That's the same problem you have with IndieAuth --Notizblog.org 06:32, 3 July 2013 (PDT)
- I agree, but that says nothing about what you think about the problem described above. -Www.sandeep.io 13:01, 14 July 2013 (PDT)
- The 'side project' assessment about the Google hub is both wrong and ill-intended. PubSubHubbub is actually key to Google's crawling capabilities and we can safely expect Google to keep maintaining it. (unsigned comment by Julien from 2013 July)
- Why would you assume ill-intent? Google's hub does not seem like an official product/service (I haven't found any references claiming otherwise). It's just a URL and associated code. The video says nothing about the hub and only talks about Google acting like a subscriber and also emphasize very limited use: "There is a very limited amount in which we will use pubsubhubbub to help improve our crawl". Nothing about the hub is official so I have no choice but to assume it's a side-project unless you cite references clearly stating otherwise. -Www.sandeep.io 13:01, 14 July 2013 (PDT)
- I can't imagine this is true anymore, as it seems very much unmaintained. https://code.google.com/p/pubsubhubbub/ has not had any substantive changes since Bret Slatkin stopped working on it in 2011. Kylewm.com 13:59, 28 February 2015 (PST)
- There are a bunch of OSS implementations of PubSubHubbub hubs that *you* you use, or you could also write your own. Not sure why this would not be a *healthy situation*... :0 (unsigned comment by Julien from 2013 July)
- If I don't want to take on the complexity of running a hub (which IMO, is what is attractive about PuSH) and pending clarification of the official status of Google's hub, there is only one hosted hub "out there" which makes it a SPOF. -Www.sandeep.io 13:01, 14 July 2013 (PDT)