Push Service Application Notes
Abstract
This document describes the Push Service Route (webhook) feature, specifications, and configuration as required.
Pre-Requisites
To create a Push Service Route (webhook) the user has be to have the following access level:
- User account with Dealer Access level.
How do I Create/Edit a Routes?
The following are the steps to Create/Edit a Route.
- Select an account
- After selecting the account, right-click on the account
- Select and click on "Edit Account"
- From the Edit page select "Routes"
- From here you can "Add Route" or right-click and "Edit Route"
The endpoint should accept post request with JSON body and return http status code 200/201/202
How do I Configure a Route?
On this page
- Enter the desired Name for the route/webhook
- Enter the Url (Endpoint which should accept post request with JSON body)
- Enable it if you would like the route to active when created
- Specify desired Headers such as
- User-Agent:
- accountKey:
- api-Key:
- Define filters, if you want to send only data that falls under these categories
- IMEIs: IDs for specific devices you want the data deliverd to endpoint.
- Tags: Specific Tag(s) you are interested in
- Groups: Specific group(s)
Route Return_Status codes:
- 200, 201, 202, 500, or 400, these are reported as Success.
- Any other error codes i.e. 401 etc... are reported as Failure. In this case Push Service will retry again.
BeWhere "Data Retention Policy" for Push Service is 7 days. Data older than 7(seven) days will be deleted.
How do I setup custom format?
The default webhook payload does not have all the data elements possible such as tags,sidSender,location,distance,totalRuntime and battery_capacity properties:
{
"sensorData": {
"eventType": "$$eventType",
"direction": "$$direction",
"navStat": "$$navStat",
"mnc": "$$mnc",
"speed": "$$speed",
"impact": "$$impact",
"rsrp": "$$rsrp",
"temperature": "$$temperature",
"altitude": "$$altitude",
"latitude": "$$latitude",
"batteryLevel": "$$batteryLevel",
"aux1": "$$aux1",
"aux2": "$$aux2",
"aux3": "$$aux3",
"aux4": "$$aux4",
"aux1_json": "$$aux1_json",
"sim": "$$sim",
"urat": "$$urat",
"hdop": "$$hdop",
"timestamp": "$$timestamp",
"mcc": "$$mcc",
"lac": "$$lac",
"pressure": "$$pressure",
"locationSource": "$$locationSource",
"received": "$$received",
"cid": "$$cid",
"numSvs": "$$numSvs",
"light": "$$light",
"longitude": "$$longitude",
"humidity": "$$humidity",
"imsi": "$$imsi"
},
"networkLocation": {
"latitude": "$$networkLatitude",
"longitude": "$$networkLongitude",
"accuracy": "$$networkAccuracy"
},
"deviceInfo": {
"imei": "$$imei",
"serialNumber": "$$serialNumber",
"sender": "$$sender",
"version": "$$version",
"name": "$$name"
}
}
In case these additional fields need to be captured in the webhook payload, a custom payload can be set up by selecting the "Post JSON format" box. Copy and paste the content from the following code into the textbox when you set up Routes.
{
"sensorData": {
"eventType": "$$eventType",
"direction": "$$direction",
"navStat": "$$navStat",
"mnc": "$$mnc",
"speed": "$$speed",
"impact": "$$impact",
"rsrp": "$$rsrp",
"temperature": "$$temperature",
"altitude": "$$altitude",
"latitude": "$$latitude",
"batteryLevel": "$$batteryLevel",
"battery_capacity": "$$battery_capacity_counter",
"aux1": "$$aux1",
"aux2": "$$aux2",
"aux3": "$$aux3",
"aux4": "$$aux4",
"aux1_json": "$$aux1_json",
"sim": "$$sim",
"urat": "$$urat",
"hdop": "$$hdop",
"timestamp": "$$timestamp",
"mcc": "$$mcc",
"lac": "$$lac",
"pressure": "$$pressure",
"locationSource": "$$locationSource",
"location": "$$location",
"received": "$$received",
"cid": "$$cid",
"numSvs": "$$numSvs",
"light": "$$light",
"longitude": "$$longitude",
"humidity": "$$humidity",
"imsi": "$$imsi",
"distance": "$$odometer",
"totalRuntime": "$$totalRuntime"
},
"networkLocation": {
"latitude": "$$networkLatitude",
"longitude": "$$networkLongitude",
"accuracy": "$$networkAccuracy"
},
"deviceInfo": {
"imei": "$$imei",
"serialNumber": "$$serialNumber",
"sender": "$$sender",
"version": "$$version",
"name": "$$name",
"sidSender": "$$sidSender",
"tags": "$$tags"
}
}
Additional properties for push format are supported below:
$$gpsTimestamp,
$$gpsTimestamp_seconds,
$$timestamp_seconds,
$$battery_capacity_counter -- return message counter if the device is Battery device or battery percentage if the device is not Battery device. If the returned value ends with "%", it indicates the battery percentage, otherwise it represents the message counter.
Advanced Route Configuration
This is optional and only required when users would like to add another security layer over the payload. Note the webhook transmission is already secure (https).
To cryptographically secure the transmission use of “seed-userid” as a header key and the account api-dealer-user in the value will add and signature to the header “hash-key”
For the hash-key added to the header, Push Service is using HMAC-SHA-512 cryptographic method to encrypt the payload. The Secret-Key will be the seed-userID's API-KEY of the dealer user account specified in header value.
API KEY in this case should not be manually generated ONLY via API call from a Dealer User with Special Permission Level "Super Acess". BeWhere support will not have access to this feature neither.
#If you have API key, then you can use accountid and api key to send request without calling login method
apiKey = "<provide api key>";
api.headers = {'Token': apiKey,
'Accept': 'application/json',
'Content-Type' : 'application/json'}
print(api.headers)
API Key should not be removed/changed Manually but only service that is using it should rotate the api-key.
def generateAPIKey(self, accountId, userId):
url = self.baseURL + "/accounts/" + accountId + "/users/" + userId + "/apikey"
print(url)
response = requests.get(url, headers=self.headers)
apikey = response.text
print(apikey)
#Generate user APIKey
api.generateAPIKey("2J8mLuc84N","api-dealer-user@bewhere.com")
Create/Update (rotate) Account Secure Route seed-userid
def updateAccountRoutes(self, accountId):
url = self.baseURL + "/accounts/" + accountId + "/routing";
print(url)
data = [
{
"name": "API: BeWhere testing endpoint",
"url": "https://www.bewhere.com",
"isEnabled": False,
"headers": [
{
"key": "seed-userid",
"value": "api-dealer-user@bewhere.com"
}
]
}
];
#Update account routes
api.updateAccountRoutes("2J8mLuc84N");