Custom iPhone Notifications with Prowl

 Posted on 21 Mar 2011  (Last modified on 13 Feb 2017)  |  4 minutes  |  690 words

On of my favorite iPhone feature is push notifications. However, only a few applications use these well (ESPN ScoreCenter, AP mobile, Twitter, etc.) and I’ve always wished I could write my own without creating a full blown iPhone application. Enter a simple application called Prowl. Prowl is a Growl client for iOS that pushes notifications to your iPhone, iPod touch or iPad with a simple API.

To send yourself custom push notifications, you’ll first need to buy Prowl for your iPhone (around USD$2.99). Once you’ve downloaded and installed it on your iPhone, you need to generate an API key. With that completed, you are all set to receive Prowl alerts.

Some desktop/server apps work with it out of the box (a semi-full list is at http://www.prowlapp.com/apps.php. Others like znc, flexget or Nagios require a plugin. To create you own custom alert, you’ll need to write some scripting code. I prefer using Python or Ruby for this, but there are plenty of libraries available for other languages.

Prowl API

The Prowl API is very simple:

  • add (POST) which sends notifications to your iPhone
  • verify (GET) which checks the validity of your API key

Just recently the API was updated to version 1.2 which added two new methods - retrieve/token (GET) and retrieve/apikey (GET) - which appeal mostly to website operators. They facilitate giving people your API key in a secure manner.

While the API is very simple, and you could certainly use it from the command line with a tool like curl, most people will want to use a library for their favorite programming language. I use two of these libraries, Prowly for Ruby and ProwlPy for Python.

Prowly for Ruby

The Prowly gem was written by Rafael Magana to make the Prowl API a bit more Ruby-friendly. It is dead simple to use. First, install the gem:

$ sudo gem install prowly

Then create a simple script like the one below:

require 'prowly'

# your api key from https://www.prowlapp.com/api_settings.php
my_api_key = "1234567890123456789012345678901234567890"

Prowly.notify do |n|
    n.apikey = my_api_key
    n.priority = Prowly::Notification::Priority::MODERATE
    n.application = "Prowly"
    n.event = "Notification"
    n.description = "Your server is under attack!!!"
    n.url = "http://www.myserver.com" # requires API 1.2 support
end

That is basically all there is to it. Of course, you’ll want your script to actually do something (check a stock, parse a RSS feed, etc.), but sending the prowl is really that simple. Prowly also includes a command line script to send notifications without any scripting.

Right now, the current gem has not been updated to use version 1.2 of the API. I’ve put in a pull request to get my upgrades merged in but in the meantime you can clone the updated one from my gtihub repository at https://github.com/slashk/prowly.

ProwlPy for Python

A corresponding Python library is called ProwlPy and was written by Jacob Burch and Olivier Hervieu. It is very similar to the Prowly. To use it, install the python library (which doesn’t appear to be on PyPi):

$ git clone https://github.com/jacobb/prowlpy.git
... snip ...
$ cd prowlpy
$ python setup.py install

Then just create a simple script like the ruby one above:

import prowlpy

# your api key from https://www.prowlapp.com/api_settings.php
my_api_key = '1234567890123456789012345678901234567890' # your api key
p = prowlpy.Prowl(my_api_key)
try:
    p.add('ProwlPy',
          'Notification',
          'Your server is under attack',
          1,
          None,
          "http://www.myserver.com")
except Exception,msg:
    print msg

I also upgraded this library to version 1.2 of the API and my changes have already been merged into the main repository at https://github.com/slashk/prowly.

Creating Your Own Prowl Notifiers

Once you’ve grokked the basics of using the Prowl API, it’s time to actually put it to use. To do that, you’ll need to create your own script (with whatever logic you need), have it execute at common intervals (usually via cron) and then just wait for prowl notifications to roll in.

To get you started, I’ve created a repository of scripts that I use over at https://github.com/slashk/prowl-scripts. There you’ll see a few scripts to notify you of:

I’ll be adding more as I clean up my other scripts (weather, stock prices, steep and cheap, etc).

iphone  python  ruby 

See also