The Push API is a webhook based outgoing connection to keep external systems up to date on what's happening in RadioManager.

Settings

The settings can be found in RadioManager, Station settings > API > Authenticates push messages

Connection

To connect to the Push API one needs to set up a public HTTP(s) endpoint which can accept POST requests. This endpoint as "Push url" in the settings

Authentication

As RadioManager will create a connection towards an external system, it is of course the responsibility to verify that that request actually comes from the RadioManager cluster and the correct station.

In order to identify itself RadioManager will send an "api-key" containing the key set as "Key" in the settings

Optionally, one can also set a secret which will be used to generate an HMAC encrypted hash, which can further verify authenticity. We advise to use HTTPS and just an api-key should be sufficient, but when using an unsecure HTTP connection this extra authentication layer might be preferable. For more information on this contact our support.

Triggers

Six different models can be monitored for changes: Programs, Broadcasts, Items, Presenters, Contacts and Campaigns. Every mutation on any object of these models will be trigger a message to be sent. There are four types of mutations: create, update, delete, recover. The messages are send asynchronously.

Manual Resync

In order to make sure the external system is up to date, it is possible to send a resynchronisation bulk. This resynchronisation will not replay every action, rather it assumes the external system is currently empty and thus will only send "create" actions. All these actions will be shown as triggered by the user who hit the "Manual Resync" button.

When the relevant models are selected in the settings, the "Manual Resync" button will send all Programs, Presenters and Contacts. However, when invoking a resync the user will be prompted for a date window. The resync will only send the Items, Broadcasts and Campaigns that have a "start" time within that window.

Messages

Each message will post a body with a JSON object informing the system of a change. In order to find out what change, the system needs to fetch the object through our API. This means that it is expected from the external system to take in account the rate limiting of the regular RadioManager API. We advise at least a debounce functionality to handle multiple updates on the same object shortly after each other.

A message will consist of:

• action - what type of mutation (create, update, delete, recover)
• model - what type of object (program, broadcast, item, presenter, contact, campaign)
• model_id - the ID of the object
• job_id - the ID of the message/job, to ensure linearity
• resync - boolean, set to true if this is a re-sync action
• station_id - the ID of the station
• user_id - the ID of the user who triggered the action, null when triggered by API
• api_id - the ID of the API which triggered the action, null when triggered by User

Example body:

{
    "action":"update",
    "model":"item",
    "model_id":49,
    "job_id":28428,
    "resync":false,
    "station_id":1,
    "user_id":1,
    "api_id":null
}