Newtifry API

To send messages to devices, you'll need to use the Newtifry API. It's designed to be as simple as possible to send messages.

The API is a simple REST interface that returns JSON (at the moment). The keys below show how it is done. Alternately, scripts already exist to send messages to Newtifry, and you can choose one that fits your platform and system.

Standalone Scripts

Language Description Link
PHP A basic command line PHP script that can send messages. From Dropbox
Python A basic command line Python script that can send messages. From Dropbox
PHP A basic command line PHP to send message with Pushingbox. From Dropbox

Nagios integration

If you have Nagios, you can easily integrate Newtifry to send notifications.

  1. Download one of the scripts above and put it somewhere on the server.
  2. Make sure the script is executable.
  3. Make sure the script runs - the Python script requires 2.6 or greater, and the PHP script requires 5.2 or greater (with the curl module installed).
  4. Add the following commands to your Nagios configuration, replacing the script path as appropriate. Also, you can customize the message to your liking.
    define command{
            command_name    notify-host-by-newtifry
            command_line    /usr/bin/printf "%b" "Info: $HOSTOUTPUT$\n\nDate/Time: $LONGDATETIME$\n" | /etc/nagios3/newtifry.py -s $CONTACTADDRESS1$ -t "$HOSTNAME$ is $HOSTSTATE$" -m -
            }
    
    define command{
            command_name    notify-service-by-newtifry
            command_line    /usr/bin/printf "%b" "Info: $SERVICEOUTPUT$\nDate/Time: $LONGDATETIME$" | /etc/nagios3/newtifry.py -s "$CONTACTADDRESS1$" -t "$SERVICEDESC$ on $HOSTALIAS$ is $SERVICESTATE$" -m -
            }
    	
  5. Modify the contacts to add the notification commands, and use address1 as the source key for that user. If you are already using address1 for something else, use another address field and change the commands above.
    define contact{
            ...
            service_notification_commands   notify-service-by-email,notify-service-by-newtifry
            host_notification_commands      notify-host-by-email,notify-host-by-newtifry
            ...
            address1                        aabbccddeeff00112233445566778899
            }
    	
  6. Test your configuration.

 

Zabbix Integration

If you have a Zabbix server, you can send messages with the following instructions.

  1. Set up either the PHP or Python version of the script, and test that it works. A suggestion is to place it into /etc/zabbix/alert.d.
  2. Add another script into /etc/zabbix/alert.d, called newtifry.sh, with this as the contents. Make the script executable and adjust the path to the newtifry program as appropriate.
    #!/bin/bash
    
    SOURCE=$1
    EVENT=$2
    NOTIFICATION=$3
    
    /etc/zabbix/alert.d/newtifry.py -s "$SOURCE" -t "$EVENT" -m "$3"
  3. Add a new Media type to Zabbix. (Found under Administration -> Media types). Use the following settings:
    • Description: Newtifry
    • Type: script
    • Script name: newtifry.sh
  4. Each user can now add a media type of Newtifry to their profile. In the 'send to', use the source key.

 

API Reference

Parameters

Note: the total message shouldn't be more than around 1024 bytes. The server will truncate your message field if it can to limit the message size. It will never truncate the URL or title. If it can't send the message without truncating the URL and title, the message will not be sent and you will get an error message. If your message is truncated, the response will have the truncated flag set to true. Newtifry is not designed to send long messages.

Parameter Value Description Required
format json Determines the format of the response. Only JSON is supported at the moment, so you should always send the string json. Required
source 32 character hash string The source key, given to you by the user. They generate it when they create a source. You can supply up to 10 sources at a time separated by a comma, or a single source. Required
title string The string title of this notification. Keep this short and relevant to the message. Required
message string The body of the message. This can contain a lot more detail of the message. This is optional, and will be sent as an empty string if not provided. Optional
url string An optional URL to pass along, that would give more information about the message. Optional
priority integer An optional message priority (0-3). 0 : no priority - 1 : info - 2 : warning - 3 : alert Optional
image string An optional bitmap URL to pass along, that would be displayed in the message detail screen (new in version 2.4.0). Optional

Sending the message

You can POST or GET the message to:

https://newtifry.appspot.com/newtifry

If sending to a single source (or multiple sources without error), upon success, the response will look like as below:

{
	"messages": 1,
	"size": 68,
	"truncated": false
}

If sending to multiple sources which causes some errors, the response will look like as below. The error field indicates which sources failed and why. You can compare the number of sources you sent with the messages field to see if all messages were sent.

{
	"size": 41
	"error": "46e38849bc5925945e0ae30d50bf2ea2: No source matches this key",
	"messages": 1,
	"truncated": false,
}

On complete failure, the error message is returned. The hash matches your incoming source key.

{
	"messages": 0,
	"error": "46e38849bc5925945e0ae30d50bf2ea2: Error message describing why it failed."
}