Watercoolr =========== pubsub via webhooks, or "twitter" for your applications Input ====== Native watercoolr publishers ----------------------------- Send POST request with JSON-encoded 'payload' parameter to http://watercoolr.example.com/publish 'payload' must provide at least channel name payload[:channel] and a message payload[:message]. The message will be send to all subscribers of that channel. * Example resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => '' id = JSON.parse(resp)["id"] resp = RestClient.post 'http://localhost:4567/subscribe', :data => { :channel => id, :url => 'http://localhost:8080/test-handler' }.to_json puts resp resp = RestClient.post 'http://localhost:4567/publish', :payload => { :channel => id, :message => 'HAYYYY' }.to_json puts resp You can use watercoolr to receive input from different web services, supporting webhooks. ping.fm -------- http://ping.fm/ can provide IM, E-mail, web etc. input for your webhooks. The information is coming via POST parameters - see also http://groups.google.com/group/pingfm-developers/web/working-with-a-custom-url Go to http://ping.fm/custom/ and in the "Custom URL:" box enter: http://watercoolr.example.com/pingfm You need a channel with 'pingfm' type. During the system startup one such channel is added by default. Just find it's name or create a new one - the latest created will be used. You can add then subscribers to your 'pingfm' channel. * Example # on http://ping.fm/custom/ enter http://example.com/pingfm # optional - create 'pingfm' type channel # or use the default one with id = '__pingfm__' resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => { :type => 'pingfm' }.to_json id = JSON.parse(resp)["id"] # register your subscribers and send them messages from IM, e-mail etc. GitHub ------- http://github.com/ can push notification for repository commits to your webhooks. The all information is inside JSON-encoded 'payload' parameter. See also: http://github.com/guides/post-receive-hooks From your project pages go to "Admin"|"Service Hooks" and in the "Post-Receive URLs" box enter: http://watercoolr.example.com/github You need a channel with 'github' type. During the system startup one such channel is added by default. Just find it's name or create a new one - the latest created will be used. You can add then subscribers to your 'github' channel. * Example # optional - create 'github' type channel # or use the default one with id = '__github__' resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => { :type => 'github' }.to_json id = JSON.parse(resp)["id"] PubSubHubbub ----------- watercoolr can be PubSubHubbub CALLBACK ONLY for now. To get Atom notifications from some hub: 1a. Create 'pubsubhubbub' type channel with some topic and a secret: resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => { :type => 'pubsubhubbub', :topic => 'http://example.com/feed', :secret => 'secret' }.to_json id = JSON.parse(resp)["id"] Or: 1b. If you will use Superfeedr for hub, register a channel with ID={secret superfeedr token}: TOKEN = 'YourSuperFeedrToken'.freeze resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => { :type => 'superfeedr', :id => TOKEN }.to_json id = JSON.parse(resp)["id"] 2. Add subscribers like usual (provide channel secret if needed) 3a. GAE PubSubHubBub Go to http://pubsubhubbub.appspot.com/subscribe and - Callback: http://watercoolr.example.com/hub/callback/{channel_name} - Topic: same link to RSS/Atom link, used in channel creation - Verify type, Mode - your choice - Verify token: the channel secret (default = 'change_me') 3b. Superfeedr In "Settings"|"Notifications" choose Type: "PubSubhubbub" and in the "Webhook URL" box enter: http://watercoolr.example.com/hub/callback/{YourSuperFeedrToken} Output ======= "Normal" subscribers (webhooks) -------------------------------- watercoolr can push notifications to normal webhooks. Information is divided on two parts (similar to github): - meta-information (user names, passwords etc.) inside the 'data' JSON-encoded parameter - actual data (message) - 'payload' JSON-encoded parameter To prevent security information leaks, all subscribers are created with type='debug' by default. For such subscribers, 'data' parameter is not send during the POSTs. This kind of subscribers are suitable for example for debugging (PostBin etc.). To have the 'data' parameter send to the hook, set the subscriber type to any string, different from 'debug': * Example resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => { :type => 'pingfm' }.to_json id = JSON.parse(resp)["id"] puts "adding subscribers to channel #{id}" resp = RestClient.post 'http://localhost:4567/subscribe', :data => { :channel => id, :type => 'local', :url => 'http://localhost:4567/hook/xmpp/secret/', :username => 'me_jid@jabber.com', :password => 'secret', :to => 'some_jid@xmpp.org' }.to_json puts resp resp = RestClient.post 'http://localhost:4567/subscribe', :data => { :channel => id, :url => 'http://postbin.org/xxxYYY' }.to_json puts resp resp = RestClient.post 'http://localhost:4567/publish', :data => { :channel => id, :message => 'HAYYYY' }.to_json puts resp Small webhooks library ----------------------- To be easier to start with watercoolr, it provides a small library of ready to use webhooks, accessable on the same system, where watercoolr is deployed. If the site URL is http://localhost:4567/ , the URLs for webhooks will be: http://localhost:4567/hook/:NAME/:SECRET/ where :NAME is one of ff (FriendFeed), twitter, xmpp or prowl and :SECRET is a special user, created during the initial deployment: DB[:users] << { :name => 'all', :password => '...', :service => 'hooks' } You can create also secret token per webhook, with :name => 'ff', 'twitter' or 'xmpp' DB[:users] << { :name => 'all', :password => 'secret', :service => 'hooks' } DB[:users] << { :name => 'xmpp', :password => 'token', :service => 'hooks' } xmpp webhook will be on URL: http://localhost:4567/hook/xmpp/token/ and all other webhooks - on URL: http://localhost:4567/hook/:name/secret/ Webhooks can be used like watercoolr subscribers or called directly with POST request and 'data' amd 'payload' parameters from other services (github etc.) Pushing to iPhone ------------------ 'prowl' webhook can be used to push notifications to iPhone. resp = RestClient.post 'http://localhost:4567/subscribe', :data => { :channel => id, :type => 'local', :url => 'http://localhost:4567/hook/prowl/secret/', :apikey => 'PROWL_APIKEY', :priority => 2}.to_json puts resp resp = RestClient.post 'http://localhost:4567/publish', :data => { :channel => id, :title => 'Alert!' :message => 'Call me!' }.to_json puts resp For Prowl API details see: http://forums.cocoaforge.com/viewtopic.php?f=45&t=20339 messagepub subscribers ----------------------- http://messagepub.com/ can send message to twitter, XMPP (jabber), SMS etc. There also have a ruby wrapper around their API gem install messagepub --no-rdoc --no-ri In order to use their services, subscribers with 'messagepub' type and additional data (channels, propagation etc.) need to be used. See also: http://messagepub.com/documentation/api . * Example mp = { :recipient => [ {:position => 1, :channel => 'email', :address => 'me@example.com'}, {:position => 2, :channel => 'twitter', :address => 'thetwitter'} ]} resp = RestClient.post('http://localhost:4567/subscribe', :data => { :channel => id, :type => 'messagepub', :url => 'YOURAPIKEY', :escalation => 30, :recipients => mp }.to_json) puts resp