Push API
The Push API will send every mobile-originated message from a device to your own web service as an HTTP POST.
The parameters included in the POST can vary depending on the type of device and the type of message, as described below.
You may configure multiple Push API endpoints via the Rock 7 Core user interface. Please contact your account manager if you require any assistance.
JSON or Form-Encoded
The format of the POST can be either a form-encoded post, where the parameters below will be encoded as if submitted from an HTML form.
POST messages sent using the HTTP_POST_INSECURE option will not validate security certificates. You should only use this if you are using a self signed certificate, or a root certificate that is not trusted by Operating Systems.
imei=300434062929540&device_type=GRIFFIN&serial=100015&momsn=70153268&transmit_time=2023-03-14T09%3A00%3A14Z&id=abgrGXzpmLqPnyqrDDoMnOyoKJdkeVNv&transport=GPRS&txAt=2023-03-14T09%3A00%3A14Z&at=2023-03-14T09%3A00%3A00Z&lat=51.49530&lon=-3.17030&source=GPS&sog=0.2&cog=51&averageSog=0.2&averageCog=51&alt=0&temp=0.0&battery=100&power=false&trigger=BURST
Alternatively (and preferably) we can send a JSON document in the POST body. Here's an example:
{
"txAt": "2023-03-14T09:15:04Z",
"averageCog": 328,
"temp": 0,
"JWT": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJSb2NrIDciLCJpYXQiOjE2Nzg3ODUzMDgsImFsdCI6IjAiLCJhdCI6IjIwMjMtMDMtMTRUMDk6MTA6MDFaIiwiYXZlcmFnZUNvZyI6IjMyOCIsImF2ZXJhZ2VTb2ciOiIwLjAiLCJiYXR0ZXJ5IjoiOTgiLCJjb2ciOiIzMjgiLCJkZXZpY2VfdHlwZSI6IkdSSUZGSU4iLCJpZCI6ImVKd2d6ZHBYVnhOUm5vcHJaZXdiV01EbFFHTFB2QWJrIiwiaW1laSI6IjMwMDQzNDA2MjkyOTU0MCIsImxhdCI6IjUxLjQ5NTQwIiwibG9uIjoiLTMuMTcwNDAiLCJtb21zbiI6IjcwMTU0ODcxIiwicG93ZXIiOiJ0cnVlIiwic2VyaWFsIjoiMTAwMDE1Iiwic29nIjoiMC4wIiwic291cmNlIjoiR1BTIiwidGVtcCI6IjAuMCIsInRyYW5zbWl0X3RpbWUiOiIyMDIzLTAzLTE0VDA5OjE1OjA0WiIsInRyYW5zcG9ydCI6IkdQUlMiLCJ0cmlnZ2VyIjoiQlVSU1QiLCJ0eEF0IjoiMjAyMy0wMy0xNFQwOToxNTowNFoifQ.g4AMhUDwaK-WKaaITOKMtIu8lVtsEBfJ-00ytW-c0jyGUFxNW0259Dj9JcR34NaIai-ysSTVzqXBdROsZAiZS0oTSRum9l56JwZQTE0-Zx5yUUO8AOsUqXPjsSg2lSgsnSMTiQHXOzhydL9GIkmiEVdwANeaB24AuP45__zUwjhwniUfi-Z2RTG8J22GqnQ9Q_w9Z861A0Bos7LmJEymbmcLOiDDdzfYxvVWE6GSm2y8ypBZEqhI0byNphZ5adIFM19iyqng4MVpQe0Uh9Jc49RR_IAjte3AMS4Y82lO76sM90Tu3-3Jwhj3Iq_NGpfd4735Bl-b5FR5oePP40mV3Q",
"alt": 0,
"device_type": "GRIFFIN",
"lon": -3.1704,
"sog": 0,
"transport": "GPRS",
"source": "GPS",
"trigger": "BURST",
"battery": 98,
"momsn": 70154871,
"averageSog": 0,
"at": "2023-03-14T09:10:01Z",
"serial": 100015,
"imei": "300434062929540",
"cog": 328,
"id": "eJwgzdpXVxNRnoprZewbWMDlQGLPvAbk",
"power": true,
"transmit_time": "2023-03-14T09:15:04Z",
"lat": 51.4954
}
JSON Web Token
The JWT parameter is signed so that you can verify that the message was sent by Ground Control. The public key is:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlaWAVJfNWC4XfnRx96p9cztBcdQV6l8aKmzAlZdpEcQR6MSPzlgvihaUHNJgKm8t5ShR3jcDXIOI7er30cIN4/9aVFMe0LWZClUGgCSLc3rrMD4FzgOJ4ibD8scVyER/sirRzf5/dswJedEiMte1ElMQy2M6IWBACry9u12kIqG0HrhaQOzc6Tr8pHUWTKft3xwGpxCkV+K1N+9HCKFccbwb8okRP6FFAMm5sBbw4yAu39IVvcSL43Tucaa79FzOmfGs5mMvQfvO1ua7cOLKfAwkhxEjirC0/RYX7Wio5yL6jmykAHJqFG2HT0uyjjrQWMtoGgwv9cIcI7xbsDX6owIDAQAB
-----END PUBLIC KEY-----
Response
It is essential that your web service implementation of the Push API endpoint responds correctly. Our service requires an HTTP 200 response to indicate successful delivery - our service will then consider the message to be delivered, and no further retry attempts will be made.
Any other HTTP response will be considered a ‘temporary‘ failure, and our service will exponentially back off and retry for up to 1 week.
POST parameters
The table below describes the parameters which MAY be included.
Note that if the trigger parameter is set to CONFIG_REPORT, then you may also receive all/any of the configuration parameters described in the Get Configuration
| Parameter | Description | Example/Possible Values |
|---|---|---|
| id | Unique ID for this report | PAjovqQGZaLRENlxJpMmnlKkpxwgdzDY |
| transport | Message transport method | IRIDIUM, GPRS, OTHER |
| imei | IMEI of Iridium device (only present for ROCKBLOCK device types) | 15 digits |
| device_type | Type of device. This may be set to LEOPARD which refers to the family of products including RockSTAR and Yellowbrick v3. TIGERSHARK refers to the family of devices including RockFLEET and YB3i. GRIFFIN refers to RockAIR | LEOPARDROCKBLOCKTIGERSHARKGRIFFIN |
| serial | The serial number of the device. | An integer |
| momsn | The MOMSN of the SBD transmission. The MOMSN is a counter stored in the Iridium device, incremented upon transmission. | An integer |
| transmit_time | Timestamp that the message was transmitted. | e.g. 2014-02-14T13:55:16Z |
| at | GPS timestamp of transmitted position. | e.g. 2014-02-14T13:54:48Z |
| iridium_longitude | The approximate longitude of the device, derived by the Iridium satellites. | e.g. -5.1841 |
| iridium_latitude | The approximate latitude of the device, derived by the Iridium satellites. | e.g. 50.9009 |
| cep | The accuracy, in km, of the Iridium derived position. | An integer |
| trigger | The reason for this transmission to have been triggered. | ROUTINEBURSTMANUALACTIVATIONDEACTIVATIONCONFIG_REPORTWAYPOINTMESSAGEACKNOWLEDGEBLUETOOTH_LOSSCOLLISIONCOUNTDOWNDEAD_MANGEOFENCEBUTTONCANCEL_ALERTPOWER_LOSSPOWER_GAINTEMPERATUREGENERICBLE_RAWSERIAL_RAWMAILBOX_CHECKAPP_MESSAGEWATCHING_START_REQUESTWATCHING_STOP_REQUEST |
| source | An indicator of whether the transmission includes a valid GPS fix. | GPSIRIDIUM |
| lat | GPS latitude | 50.88886 |
| lon | GPS longitude | -1.29198 |
| sog | Speed over ground (in knots) | e.g. 0.1 |
| cog | Course over ground | e.g. 302 |
| averageSog | Speed over ground (in knots) – averaged from last two positions | e.g. 0.1 |
| averageCog | Course over ground – averaged from last two positions | e.g. 302 |
| alt | GPS altitude (in metres) | e.g. 22 |
| temp | Temperature (degrees Celsius) | e.g. 4.5 |
| battery | Battery level, in percent | e.g. 99 |
| power | Indicates presence of external DC power | true, false |
| message | A text message sent from the device. | e.g. All fine |
| ack_request | The id of a text message sent FROM the device, to be used when acknowledging. | e.g. 123 |
| userData | Data payload from device | e.g. 48656c6c6f20576f726c64 |
| message_ack | The id of a text message previously sent TO the device, which the device is acknowledging. | e.g. 321 |
| alert | Indicator of whether or not this transmission was triggered by an alert condition. | truefalse |
| waypoint | The name of the waypoint, as selected by the device user. | e.g. Bridge |
| appMessageAddress | The comma-separated list of addresses for recipients specified by the user of an i360 CONNECT App. | someone@gmail.com,<br />4477701233321 |
| appMessageContent | The message content for a message sent using the i360 CONNECT App | |
| beacons | The comma-separated list of beacons that have been observed | DA01:6969,A10A:EF01 |
| ext_ref | An External Reference can be set in the CORE to help identify devices with a user defined ID. | Returns user specified reference |
📘 Iridium position reports
We can report transmissions to you that may not have a valid GPS fix. Typically this happens if it has a poor view of the sky, but there are other occasions when it will transmit a message without a GPS position. In this case, we do get an approximate position from the Iridium network. This ranges in accuracy - often it can be within a few km, or it may be 200km out.
There is a source="GPS" or source="IRIDIUM" parameter in every
element. If it's an Iridium position, you won't get sog, cog or alt parameters. You will get a cep="123" parameter, which indicates the accuracy (in km) of the reported position.
It's necessary for us to tell you about Iridium positions, because it is possible that the tracker can report an alert with no GPS fix.
Alerts
If a tracker transmits an 'alert' message, you will see an alert parameter. Alert types are further defined by alertType or genericType parameters. A table of alert types can be found below:
| alertType | Meaning | trigger |
|---|---|---|
| BUTTON | The user has pressed the red alert button | |
| BT_LOST | The bluetooth connection has been lost | |
| COLLISION | A collision alert | |
| COUNTDOWN | The countdown timer has timed-out | |
| DEAD_MAN | The dead-man timer wasn't reset in time | |
| GEOFENCE | The tracker has moved too far from its geofence centre | |
| CANCEL | The user has cancelled any previous alerts (this is a menu option on the tracker). | |
| POWER | External power state change | POWER_LOSS POWER_GAIN |
| RESET_EXTERNAL | Hard reset performed on physical tracker | GENERIC |
| TEMPERATURE | Temperature outside preset range. | |
| POLYFENCE | The tracker has transmitted because it crossed a polyfence boundary. | |
| SWITCH_A_RISING SWITCH_A_FALLING SWITCH_B_RISING SWITCH_B_FALLING SWITCH_C_RISING SWITCH_C_FALLING SWITCH_D_RISING SWITCH_D_FALLING SWITCH_E_RISING SWITCH_E_FALLING | Activity occurred on an external input | |
| HOVER_ENTRY HOVER_EXIT | RockAIR specific feature - hover detection events | |
| TAKE_OFF LANDING STOPPED MOVING | RockAIR specific feature - events for fixed-wing aircraft to represent stopped (on blocks), moving (off-blocks), take-off and landing. | |
| TRACKING_SUSPEND TRACKING_AUTO_RESUME TRACKING_MANUAL_RESUME | Suspend/resume events | |
| EXCESSIVE_DESCENT_RATE EXCESSIVE_ASCENT_RATE | Excessive rate of change of altitude events | |
| WAYPOINT_A WAYPOINT_B WAYPOINT_C WAYPOINT_D | Waypoint events |