= webhook-pirate

== What Is It?

webhook Campfire bot and "speak" REST API. Teeny regex->hook dispatcher.

== More

You can run hookfire, sheepie, or both:

• hookfire: poor man's Campfire REST interface (as Sinatra app). Exposes /speak (GET and POST). Takes 1 param 'message' and sends verbatim to Campfire. Optionally, match & pre-process requests via a webhook (hookfire_hooks.json). Deployable on Heroku.

• sheepie: daemonized webhook-backed Campfire bot. Idles until addressed, then compares request to per-action regexes (sheepie_hooks.json). Upon match, calls action URL to generate reply.

• pirate: regex/hook URL tracker and dispatcher library. Tracks & fires lightweight HTTP targets. Returns responses.

== Setup & Config

1. Run: sudo gem install tinder active_support json rest-client

2. Edit campfire.json.sample and save as campfire.json

   If using sheepie: set 'bot_name' to whatever other people will address the bot as. Doesn't need to match its Campfire name, just what people type.

   If using hookfire: optionally set 'key' to random string for authorization, so strangers can't guess URL. If set, HTTP requests must include this as the 'key' param.

3. Run: ruby bin/hookfire.rb campfire.json hookfire_hooks.json & and/or ruby bin/sheepie.rb campfire.json sheepie_hooks.json &

Run them backgrounded, use screen, or otherwise daemonize. When no arguments are provided, they look for the filenames above.

Usual Sinatra arguments apply to hookfire: ruby bin/hookfire.rb -p 12345

== hookfire

By default, inbound messages are sent directly to the channel as-is.

To process messages from less-flexible calling services, make a HTTP target which accepts 1 GET param called 'message', munges, and outputs whatever should go to the channel (as response body). Then edit hookfire_hooks.json; define the URL and a regex to match relevant 'message' values. Use this when the caller is really verbose or you want to reformat its input.

=== Example: Google Reader "Send to Campfire"

In Google Reader, go to Settings -> Send To. Hit "Create a custom link." Use:

Name: Campfire URL: http://your.hookfire.url/speak?key=kerfluffle&message=Troy has shared ${title} from ${source}. ${short-url} Icon URL: http://campfirenow.com/favicon.ico

Save. You'll see a new option on each article's Send To link. Everyone in Campfire will respect your awesome taste in RSS.

=== Running hookfire on Heroku

Without forking this repo, you can deploy to Heroku and have your own Campfire 'speak' URL in about 3 minutes. The webhook regexes/URLs can even be customized. Either:

A. Don't fork the repo: edit the config files, commit, and only push to Heroku. You won't be able to push to the main github repo, but that's not required. Don't lose your config files. -- OR -- B. Fork the repo: edit the config files, commit, and push to Heroku or to your repo. Should work as-is: hookfire defaults to the standard config filenames when none are given, and the config.ru will start it on Heroku.

For A or B: git clone cp campfire.json.sample campfire.json vi campfire.json hookfire_hooks.json git add -f campfire.json # force; this file is .gitignored git commit -a

sudo gem install heroku heroku create some-neat-hostname git remote add heroku [email protected]:some-neat-hostname.git git push heroku master

Voila: http://some-neat-hostname.heroku.com/speak?message=baah&key=whatever

Note: sheepie bot won't run on Heroku (no daemons)

More: http://docs.heroku.com/

== sheepie

sheepie lets you add third-party services to Campfire.

When the bot is addressed, it matches the message against regexes configured in sheepie_hooks.json, then calls the first matching hook URL (if any). Hook response body is spoken in Campfire.

Preconfigured with these commands:

• Count Google results. Example: sheepie: gcount "wu tang forever"

Runs against: http://www.scriptlets.org/view/1ffqh5b

• Inline someone's most recent tweet as a Twictur.es image. Example: sheepie: @cloudvox

Runs against: http://www.scriptlets.org/view/12z9upp

== Notes

All HTTP handlers and requests are synchronous and block. "High volume" in this context is once per minute, so you should be safe.

You're on your own if the preconfigured hook scripts break. They may be updated/changed in the future (in which case, URLs will change).

Fork requests welcome.

== Contact

Troy Davis

http://twitter.com/troyd (@troyd)

http://troy.yort.com/