Back to top
Home / Knox Webhook Notification / Tutorial /

Knox Webhook Notification for Knox Asset Intelligence

Last updated October 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 the Knox Asset Intelligence API, you can authenticate using one of the following methods:

a. Generate an access token through Knox OAuth 2.0 Authentication.

b. Generate an access token that doesn’t use OAuth 2.0 authentication. See Knox Cloud API Authentication tutorial for customers for more information.

Certificate

The Samsung Knox validation certificate is required to validate the response you’ll receive from Knox Webhook Notification. Download the certificate using the GET /downloadCertificate operation.

Alternatively, you can download the certificate by clicking the following button.

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:

{
    "event": "KAI_APP_USAGE_TIME_BATTERY",
    "subscriptionId": "123456789123",
    "payload": {
        "serialNumber": "EX4MP13",
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "groupName": "Example Group",
        "model": "Example Device",
        "firmwareVersion": "4.14.190-23230211-abG973WVLS6HVA1",
        "osVersion": "Android 11",
        "updatedTime": 1692994420,
        "timeZone": "EST",
        "usageDetail": [
            {
                "appName": "Android System WebView",
                "appVersion": "98.0.4606.89",
                "packageName": "com.google.android.webview",
                "appUID": 3,
                "foregroundTime": 218,
                "backgroundTime": 664,
                "batteryUsage": 8.439181,
                "collectionStartTime": 1698821434171,
                "collectionEndTime": 1698822315340,
                "timeZone": "EST"
            },
            {
                "appName": "Example app",
                "appVersion": "2.1.2",
                "packageName": "com.digibites.accubattery", 
                "appUID": 3,
                "foregroundTime": 0,
                "backgroundTime": 882,
                "batteryUsage": 0.172311,
                "collectionStartTime": 1698821434171,
                "collectionEndTime": 1698822315340,
                "timeZone": "EST"
            }
        ]
    }
}

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:

{
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "serialNumber": "EX4MP13",
        "groupName": "Example Group",
        "model": "Example Device",
        "firmwareVersion": "4.14.190-23230211-abG973WVLS6HVA1",
        "osVersion": "Android 13",
        "updatedTime": 1692994420,
        "timeZone":"EST",
        "usageDetail": [
            {
                "appName": "Example app",
                "appVersion": "1.1.10.3",
                "packageName": "com.example.android",
                "appUID": 3,
                "mobileBackgroundUsage": 0,
                "mobileForegroundUsage": 0,
                "mobileUsage": 0,
                "wifiBackgroundUsage": 0,
                "wifiForegroundUsage": 19523071,
                "wifiUsage": 19523071,
                "collectionStartTime": 1692758400000,
                "collectionEndTime": 1698878900000,
                "timeZone": "EST"
            },
            {
                "appName": "My example app",
                "appVersion": "15.22.18",
                "packageName": "com.google.android",
                "appUID": 3,
                "mobileBackgroundUsage": 0,
                "mobileForegroundUsage": 0,
                "mobileUsage": 0,
                "wifiBackgroundUsage": 139108,
                "wifiForegroundUsage": 0,
                "wifiUsage": 139108,
                "collectionStartTime": 1698818400000,
                "collectionEndTime": 1698825600000,
                "timeZone": "EST"
            }
        ]
    }
}

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:

{
    "event": "KAI_APP_USAGE_SCREENTIME",
    "subscriptionId": "123456789123",
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "serialNumber": "EX4MP13",
        "groupName": "Example group",
        "model": "Example Model",
        "firmwareVersion": "4.14.190-23230211-abG973WVLS6HVA1",
        "osVersion": "Android 13",
        "updatedTime": 1698822005913,
        "timeZone": "EST",
        "usageDetail": [
            {
                "appName": "Example app",
                "appVersion": "1.1.67.5",
                "packageName": "com.example.android",
                "appUID": 3,
                "openCount": 3,
                "screenTime": 2804,
                "collectionStartTime": 1698818400000,
                "collectionEndTime": 1698822000000,
                "timeZone": "EST"
            },
            {
                "appName": "Example app",
                "appVersion": "98.0.4606.89",
                "packageName": "com.google.android.example.webview",
                "appUID": 1,
                "openCount": 1,
                "screenTime": 2,
                "collectionStartTime": 1698818400000,
                "collectionEndTime": 1698822000000,
                "timeZone": "EST"
            }
        ]
    }
}

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:

{
    "subscriptionId" : "123456789123",
    "event" : "KAI_APP_ANR_FC",
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "serialNumber" : "EX4MP13",
        "appName": "Android System WebView",
        "appVersion": "98.0.4606.89",
        "packageName": "com.google.android.webview",
        "class": "com.samsung.android.knox.rtls.ui.view.landing.TabVenueFragment",
        "callStack": "java.lang.NullPointerException: Attempt to invoke interface method 'int java.util.List.size()' on a null object reference at com.samsung.android.knox.rtls.ui.view.landing.TabVenueFragment.onViewCreated(TabVenueFragment.java:72)",
        "osVersion": "Android 11",
        "firmwareVersion": "4.14.190-23230211-abG973WVLS6HVA1",
        "model": "Example Device",
        "issueType": "ANR",
        "groupName": "Example Group",
        "updatedTime": 1692994420,
        "timeZone": "EST"
    }
}

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:

{
    "subscriptionId" : "123456789123",
    "event" : "KAI_BATTERY_STATUS",
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "serialNumber" : "EX4MP13",
        "groupName": "Example Group",
        "model": "Example Device",
        "updatedTime": 1692989890863,
        "timeZone": "EST",
        "batteryChargingType": "",
        "batteryChargingPlug": "N/A",
        "batteryLevel": 74,
        "batteryRemainingTime": 1118,
        "batterySoh": "Good",
        "batterySohValue": 99,
        "batteryStatus": "Discharging",
        "batteryChargingCycle": 29,
        "fullChargeBatteryTime": 1511
    }
}

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:

{
    "event": "KAI_BATTERY_CHARGING",
    "subscriptionId":"566797f70f280325c20ff234",
    "payload": {
       "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "batteryChargingType":"Fast(PD)",
        "batterySoh":"Good",
        "updatedTime":1698640685534,
        "groupName":"Example group",
        "serialNumber":"EX4MP13",
        "batterySohValue":100,
        "timeZone":"EST",
        "model": "Example Model",
        "batteryChargingPlug":"AC",
        "batteryLevel":33
    }
}

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:

{
    "event":"KAI_BATTERY_LEVEL_SHIFT_END",
    "subscriptionId": "678778f70f280325c20ff999",
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "updatedTime":1698822002333,
        "batterySoh":"Good",
        "groupName":"Example group",
        "serialNumber":"EX4MPL3",
        "batterySohValue":100,
        "timeZone":"EST",
        "model": "Example Model",
        "batteryRemainingTime":2370,
        "batteryLevel":79
    }
}

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:

{
    "event": "KAI_BATTERY_LEVEL_TRIGGERED",
    "subscriptionId": "653085f70f789456c20ff019",
    "payload": {
        "batterySoh": "Good",
        "updatedTime": 1698819058359,
        "serialNumber": "EX4MPL3",
        "timeZone": "EST",
        "batteryRemainingTime": 2440,
        "groupName": "Example group",
        "batteryChargingCycle": 81,
        "fullChargeBatteryTime": 3000,
        "batteryStatus": "Discharging",
        "batterySohValue": 100,
        "model": "Example Model",
        "batteryChargingPlug": "N/A",
        "batteryLevel": 85
    }
}

Wi-Fi connections

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_CONNECTIONS event to get notified when a device connects to a wireless access point.

Step 2: Handle response message

Once the event is complete, you’ll receive the following message in the body of the subscribed URL call as the response payload:

{
    "event": "KAI_WIFI_CONNECTIONS",
    "subscriptionId": "2123456789123",
    "payload": {
        "serialNumber": "EX4MP13",
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "groupName": "Example Group",
        "bssid": "13:99:b2:0c:5b:23",
        "ssid": "Example wifi zone_secure",
        "vendorName": "Android 13",
        "oui": "13:99:b2",
        "rssi": -83,
        "channel": 60,
        "bands": 5.0,
        "linkspeed": 78,
        "updatedTime": 1700694634050,
        "timezone": "Asia/Seoul",
        "friendlyBssid" : "abcd"
    }
}

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:

{
    "subscriptionId" : "123456789123",
    "event" : "KAI_WIFI_DISCONNECTIONS",
    "payload": {
        "imei": "123456789",
        "serialNumber" : "EX4MP13",
        "groupName": "Example Group",
        "localGenerated": "GENERATED_BY_DEVICE",
        "disconnectionCategory": "3rd Party App",
        "disconnectionEvent": "Caused by 3rd Party App",
        "disconnectionReasonCode": "36",
        "disconnectionReason": "Requesting STA is leaving the BSS (or resetting) (36)",
        "bssid": "00:30:00:00:00:00",
        "ssid": "DAI_DEV_2.5G",
        "vendorName": "Example Vendor",
        "oui": "e8:07:bf",
        "accessPointType": "APTYPE_PASSPOINT",
        "frequency": "5000",
        "screenState": "SCREEN_OFF",
        "powerSavingMode": "POWER_OFF",
        "updatedTime": 1692989890863,
        "timeZone": "EST"
    }
}

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:

{
    "subscriptionId" : "123456789123",
    "event" : "KAI_DEVICE_DIAGNOSTICSLOGS",
    "payload": {
        "imei": "123456789",
        "imei1": "123456789",
        "imei2": "465789132",
        "serialNumber" : "EX4MP13",
        "logId": "64e851ddc136352a60a5e1a0",
        "status": "Completed",
        "downloadLink": "https://example-download-link.com/log.zip",
        "groupName": "Example Group",
        "updatedTime": 1692989890863
    }
}

Verify the response

To verify the Knox Webhook Notification callback response:

  1. Get the String value of HttpRequestPayload
byte[] inputStreamBytes = StreamUtils.copyToByteArray(request.getInputStream());
Map jsonBody = objectMapper.readValue(inputStreamBytes, HashMap.class);
String requestBody = objectMapper.writeValueAsString(jsonBody);
  1. Parse the encoded JoseHeader and signature from X-WSM-SIGNATURE
String[] jwsParts = jwsSignature.split("\\.");
if (jwsParts.length != 3) {
    // Invalid JWS signature
    return new ResponseEntity<>("Invalid JWS signature: X-WSM-SIGNATURE=" + jwsSignature, HttpStatus.BAD_REQUEST);
}

String encodedHeaders = jwsParts[0];
String encodedRequestBody =  Base64.getUrlEncoder().encodeToString(requestBody.getBytes(StandardCharsets.UTF_8));
String signature = jwsParts[2];
  1. Prepare the data to verify: DataToVerify = encodedJoseHeader.Base64UrlEncode(HttpRequestPayload)
String dataToVerify = encodedHeaders + "." + encodedRequestBody;

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

    verify(DataToVerify, Base64UrlDecode(Signature))

byte[] signatureByte = Base64.getUrlDecoder().decode(signature);

Signature rsaSignature = Signature.getInstance("SHA256withRSA");

// Pre-download Samsung certificate and store it locally with your application. Load public key from locally stored cert file.

rsaSignature.initVerify(publicKey);  
rsaSignature.update(dataToVerify.getBytes(StandardCharsets.UTF_8));
boolean verified = rsaSignature.verify(signatureByte);
if (verified) {
    // Process the result
    // ADD BUSINESS LOGIC, return OK
    return new ResponseEntity<> ("Result is processed successfully", HttpStatus.OK);
} else {
    return new ResponseEntity<>("Signature validation failed: X-WSM-SIGNATURE=" + jwsSignature, HttpStatus.INTERNAL_SERVER_ERROR);
}

Complete code

public ResponseEntity receiveResult(HttpServletRequest request,
@Valid @NotBlank @RequestHeader(value="X-WSM-SIGNATURE") String jwsSignature,
@Valid @NotBlank @RequestHeader(value="X-WSM-TRACEID") String transId) {
    try {
        // 1. Get the request body
        byte[] inputStreamBytes = StreamUtils.copyToByteArray(request.getInputStream());
        Map jsonBody = objectMapper.readValue(inputStreamBytes, HashMap.class);
        String requestBody = objectMapper.writeValueAsString(jsonBody);

        // 2. Verify the data and signature
        String[] jwsParts = jwsSignature.split("\\.");
        if (jwsParts.length != 3) {
            // Invalid JWS signature
            return new ResponseEntity<>("Invalid JWS signature: X-WSM-SIGNATURE=" + jwsSignature, HttpStatus.BAD_REQUEST);
        }

        String encodedHeaders = jwsParts[0];
        String encodedRequestBody =  Base64.getUrlEncoder().encodeToString(requestBody.getBytes(StandardCharsets.UTF_8));
        String signature = jwsParts[2];

        String dataToVerify = encodedHeaders + "." + encodedRequestBody;
        byte[] signatureByte = Base64.getUrlDecoder().decode(signature);

        Signature rsaSignature = Signature.getInstance("SHA256withRSA");

        // Pre-download Samsung certificate and store it locally with your application. Load public key from locally stored cert file.

        rsaSignature.initVerify(publicKey);  
        rsaSignature.update(dataToVerify.getBytes(StandardCharsets.UTF_8));
        boolean verified = rsaSignature.verify(signatureByte);
        if (verified) {
            // 3. Process the result
            // ADD YOUR BUSINESS LOGIC, return OK
            return new ResponseEntity<> ("Result is processed successfully", HttpStatus.OK);
        } else {
            return new ResponseEntity<>("Signature validation failed: X-WSM-SIGNATURE=" + jwsSignature, HttpStatus.INTERNAL_SERVER_ERROR);
        }
    } catch (Exception e) {
        log.error("receiveResult: failed to verify or parse request body", e);
        return new ResponseEntity<>("Internal error: " + e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

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.

On this page

Is this page helpful?