Back to top

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:

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 CERTIFICATE

Use the Knox Webhook Notification API

Battery data of app usage

Step 1: Subscribe an event

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.

  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.

  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.

  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.

  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.

  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.

  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.

  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.

  3. Register the KAI_BATTERY_LEVEL_SHIFT_START and KAI_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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.

  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.

  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
  3. 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

  1. Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions.
  2. Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results.
  3. 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:

  1. Get the String value of HttpRequestPayload
  1. Parse the encoded JoseHeader and signature from X-WSM-SIGNATURE

  2. Prepare the data to verify: DataToVerify = encodedJoseHeader.Base64UrlEncode(HttpRequestPayload)

  1. Decode the signature with Base64Url decoder and verify the data above by using SHA256withRSA

    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:

  1. Use customerA to create the subscription using the Knox Webhook Notification Subscription API.
  2. Configure example.com/kwn_result/customerA as the callback URL.
  3. 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.

Is this page helpful?