Knox Webhook Notification for Knox Asset Intelligence
Last updated January 15th, 2024
The following tutorials will help you get started on using the Knox Webhook Notification API for Knox Asset Intelligence.
Currently, the Knox Webhook Notification API supports the following Knox Asset Intelligence events:
- Battery data of app usage
- Network data of app usage
- Screen time data of app usage
- Battery charging
- Battery level at shift start or end
- Battery data triggered by threshold level
- App no response and force close
- Wi-Fi disconnections
- Battery status
- Device diagnostics logs
Prerequisites
Registration
To successfully make calls to the Knox Asset Intelligence API, ensure that you’ve configured Knox Asset Intelligence in the Knox Admin Portal and enrolled your managed devices in Knox Asset Intelligence. See Get started with Knox Asset Intelligence for details.
Authentication
To get started with using the Knox Asset Intelligence API, you need an authentication token. For more information, see Knox Cloud API Authentication tutorial for customers.
Certificate
Download your Samsung Knox validation certificate. You’ll need this to validate the response you’ll receive from Knox Webhook Notification.
DOWNLOAD CERTIFICATEUse the Knox Webhook Notification API
Battery data of app usage
Step 1: Subscribe an event
-
Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
-
Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
-
Register the
KAI_APP_USAGE_TIME_BATTERY
event to asynchronously monitor the battery data of app usage and its details. Knox Asset Intelligence provides battery status information every three hours periodically. Multiple data points collected over 3 hours are delivered separately based on the collection start or end time.
Step 2: Handle response message
Every three hours, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Network data of app usage
Step 1: Subscribe an event
-
Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
-
Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
-
Register the
KAI_APP_USAGE_NETWORK
event to asynchronously monitor the mobile network data of app usage and its details. Knox Asset Intelligence provides data usage information every two hours periodically.
Step 2: Handle response message
Every two hours, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Screen time data of app usage
Step 1: Subscribe an event
-
Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
-
Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
-
Register the
KAI_APP_USAGE_SCREENTIME
event to asynchronously monitor the screen time and app launching count data of app usage and its details. Knox Asset Intelligence provides this usage information every three hours periodically. Multiple data points collected over 3 hours are delivered separately based on the collection start or end time.
Step 2: Handle response message
Every three hours, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Battery charging
Step 1: Subscribe an event
- Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
- Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
- Register the
KAI_BATTERY_CHARGING event
to asynchronously receive details about the battery charging event as it occurs.
Step 2: Handle response message
After Knox Asset Intelligence finishes uploading the battery charging logs, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Battery level at shift start or end
Step 1: Subscribe an event
-
Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
-
Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
-
Register the
KAI_BATTERY_LEVEL_SHIFT_START
andKAI_BATTERY_LEVEL_SHIFT_END
events to asynchronously monitor the device battery levels and details at the start and end of a device usage work shift respectively.
Step 2: Handle response message
When the device starts or ends a work shift, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Battery data triggered by threshold level
Step 1: Configure threshold value
Make an API call to the Set Triggered threshold of Battery level API to set threshold values for the device battery level.
Step 2: Subscribe an event
-
Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
-
Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
-
Register the
KAI_BATTERY_LEVEL_TRIGGERED
event to asynchronously monitor the device battery levels and send a callback response when the battery level is below the triggered battery level.
Step 3: Monitor battery consumption
Once the battery level is below the set triggered value, the Knox Asset Intelligence client will generate the KAI_BATTERY_LEVEL_TRIGGERED event. You can then check the triggered values set using the Get Triggered threshold of Battery level API.
Step 4: Handle response message
When the battery level is below the configured threshold, and the event is processed, you’ll receive the following message in the body of the subscribed URL call as the response payload:
App no response and force close
Step 1: Subscribe an event
- Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation —
POST /kwn/v1/subscriptions
. - Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
- Register the
KAI_APP_ANR_FC
event to asynchronously receive ANR and FC event details. Knox Asset Intelligence checks for ANR and FC events every hour and only posts event details if there have been any new issues since the previous check.
Step 2: Handle response message
If there’s been an ANR/FC event, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Wi-Fi disconnections
Step 1: Subscribe an event
- Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation —
POST /kwn/v1/subscriptions
. - Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
- Register the
KAI_WIFI_DISCONNECTIONS
event to asynchronously receive abnormal Wi-Fi disconnection event details as they occur.
Step 2: Handle response message
In the event of an abnormal Wi-Fi disconnection, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Battery status
Step 1: Subscribe an event
- Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation —
POST /kwn/v1/subscriptions
. - Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
- Register the
KAI_BATTERY_STATUS
event to asynchronously receive battery status details. Knox Asset Intelligence provides battery status information every three hours periodically.
Step 2: Handle response message
Every three hours, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Device diagnostics logs
Step 1: Subscribe an event
- Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation —
POST /kwn/v1/subscriptions
. - Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
- Register the
KAI_DEVICE_DIAGNOSTICSLOGS
event to asynchronously receive the device diagnostics log once it’s complete. Knox Asset Intelligence can take up to five minutes to generate the log file.
Step 2: Generate device diagnostics logs
The generating operation makes an API call to the Knox Asset Intelligence generate device diagnostics logs operation.
Step 3: Handle response message
After Knox Asset Intelligence finishes generating the device diagnostics log, you’ll receive the following message in the body of the subscribed URL call as the response payload:
Verify the response
To verify the Knox Webhook Notification callback response:
- Get the String value of
HttpRequestPayload
-
Parse the encoded JoseHeader and signature from X-WSM-SIGNATURE
-
Prepare the data to verify:
DataToVerify = encodedJoseHeader.Base64UrlEncode(HttpRequestPayload)
-
Decode the signature with
Base64Url
decoder and verify the data above by usingSHA256withRSA
verify(DataToVerify, Base64UrlDecode(Signature))
Complete code
One URL for multiple subscriptions
As a customer, you can configure one URL to subscribe to multiple events, as follows:
- Use customerA to create the subscription using the Knox Webhook Notification Subscription API.
- Configure
example.com/kwn_result/customerA
as the callback URL. - Make a call to one or more supported events using the same callback URL.
Once you successfully complete these steps, the configured URL example.com/kwn_result/customerA
will receive the operation result.
On this page
Is this page helpful?