Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

OnTop Notification API



In summary, this is an api/app combo to send notifications to your phone using a GET or POST call. It's designed to keep you in the loop of whats happening while you're away from your computer. Can be used for:

  • Getting notified of new content/actions on your app that require review
  • Reporting server crashes, bugs, or situations requiring immediate attention.
  • Getting push from an internet connected device such as arduino or any IOT device (your 3d printer sending you a push that the print is done, etc.)
  • Simple app analytics and engagement studies for new apps


The idea behind OnTop has to been to make it easy for others like myself who have developed a number of apps to stay on top of what's happening with or within their apps. I'm sure there are other services that enable this but I wanted very a simple app/api combo that could be easily added with one line of code without bulky SDKs to send you push notifications to yourself. Right now I'm using it to get notified of exceptions, user actions, and app usage. But you can use it for whatever else on whichever platform or app type.

The way it works is you need to download the OnTop Notifications App on Play Store and add your app. You'll receive an app ID and SECRET KEY to use with the api. The API has only one end point to send push notifications to yourself


I also plan to provide class files for Android, PHP, and other languages soon to make the API easier to implement. If anyone wants to convert OnTop.php to any other language, just send it to me and I'll add it in.

Api docs

GET / POST Methods

Here's the full info on the GET endpoint. Aside from id and key params everything else is optional. Also you can use the category/action combo to organize your notifications in groups and manage their behaviours separately.

    id          <app id>        required
    key         <app secret>    required
    message     <Any text>      Message that will primarily be shown on the notification (250 char max)
    category    <category tag>  Add a category to represent the entities/categories. i.e. "user", "song"
    action      <action tag>    Add a action tag to represent the action performed. i.e. "like", "add", "share"
    noti_action_url <url>       If you supply a url here, it'll show up as a clickable btn at the bottom of the notification
    custom      <jSon string>   Encoded JSON String of any vars that you'd like to send with event (i.e. {"user_id":342})

In case you prefer using POST, you can also send to the same end point but add is_post=1 to the url.

            ... all the same parameters as GET

Java / Android (

To make things easier I've added a class called for use in Android applictions. Feel free to edit it as you need. There's just one dependency tho, you need LoopJ's Asynchronous Http client for Android or you can modify OnTop.send() function to use your own method. For the LoopJ plugin, add the line below to your app.gradle

compile ''

The class is easy enough to use. You can also read the docs for each method in the file to get more details.

OnTop ontop = new OnTop(YOUR_APP_ID, YOUR_APP_SECRET);
ontop.setMessage("This is a test");
//or just
new OnTop(YOUR_APP_ID, YOUR_APP_SECRET).setMessage("This is a test").send();

You can also set any of the following options to help you manage your events

// Add a category to represent the entities/categories. (i.e. "user", "song")
// Can contain only alphabet, underscore, and numbers with max 64 characters.
// Add a action tag to represent the action performed. (i.e. "like", "add", "share")
// Can contain only alphabet, underscore, and numbers with max 64 characters.
// Add a custom field to hold any meta data for future reference.
// KEY      should be a string such as "user_id", "user_name", etc
// VALUE    can be of type String, int, boolean, long, or float
ontop.setCustom(KEY, VALUE);
// Will add a clickable action button at the bottom of the notification  that'll take you to this url.
// URL      a string url (i.e.

PHP API (OnTop.php)

The PHP functions are identical to the Java version so refer to Java docs for the descriptions. Except, the send() function uses a file_get_contents method so it doesn't need a secondary library.


$ontop = new OnTop(YOU_APP_API, YOUR_APP_SECRET);
$ontop->setMessage("This is a test notification!");

Here's the sumary of availabe optional functions:

$ontop->setMessage("Text");                         // set notification msg
$ontop->setCategory("user");                        // (optional) set event category
$ontop->setAction("follow");                        // (optional) set event action
$ontop->setCustom("user_id", 324);                  // (optional) set a custom key-value pair
$ontop->setNotificationAction("");   // (optional) set a URL as an action button on the notification
$ontop->getCompiledUrl();                           // returns a compiled GET url that can be used in the browser
$ontop->send();                                     // makes the call using POST method

JS Use Example using jQuery

    type: "GET", 
    url: "", 
    data: { 
        'id' : <app id>, 
        'key' : <secret key>, 
        'message' : <Your message> 
    async: true, 
    cache: true, 
    success: function(response) { } 

To Do

Here are some additions I'm thinking of, feel free to suggest more

  • Multiple users per app (so a team can stay on top of whats happening)
  • More comprehensive event search/filtering on app side
  • Basic app stats
  • A seperate messaging api to help connect your users to you so can give them live assistance.
  • Live api tester and link generator on the app


This is a fairly new API so if there's anything that you think would be cool to add or if there's any issues please definitely let me know!


Api for Ontop app




No releases published


No packages published