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 Rock 7. The public key is:

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	`LEOPARD` `ROCKBLOCK` `TIGERSHARK` `GRIFFIN`
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.	`ROUTINE` `BURST` `MANUAL` `ACTIVATION` `DEACTIVATION` `CONFIG_REPORT` `WAYPOINT` `MESSAGE` `ACKNOWLEDGE` `BLUETOOTH_LOSS` `COLLISION` `COUNTDOWN` `DEAD_MAN` `GEOFENCE` `BUTTON` `CANCEL_ALERT` `POWER_LOSS` `POWER_GAIN` `TEMPERATURE` `GENERIC` `BLE_RAW` `SERIAL_RAW` `MAILBOX_CHECK` `APP_MESSAGE` `WATCHING_START_REQUEST` `WATCHING_STOP_REQUEST`
source	An indicator of whether the transmission includes a valid GPS fix.	`GPS` `IRIDIUM`
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`
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.	`true` `false`
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.	`[email protected], 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.