Knox Webhook Notification for Knox Guard

The following tutorials will help you get started on using the Knox Webhook Notification API for Knox Guard.

Currently, the Knox Webhook Notification API supports the following Knox Guard events:

• Device enrollment
• Device relock timestamping
• Device lock
• Device unlocking

Knox Webhook Notification sends change notifications when these events are complete.

Prerequisites

Registration

To successfully make calls to the Knox Guard APIs, register as a developer on developer.samsungknox.com and download the latest Knox SDK.

Authentication

To get started with using Knox Guard APIs, 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.

Use the Knox Webhook Notification API

Device enrollment

This tutorial demonstrates how you can use Knox Webhook Notification to call the Knox Guard device enrollment event and register it with Knox Webhook Notification to receive change notifications when the enrollment is complete.

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 once the event is complete.

3. Register the KG_DEVICE_ENROLLED event to asynchronously receive the API operation result on the device enrollment operation once it’s complete.

Step 2: Upload a device

Upload and enroll a device. Doing so makes an API call to the Knox Guard device enrollment operation.

Step 3: Handle response message

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

{
    "subscriptionId" : "123456789123",
    "event" : "KG_DEVICE_ENROLLED",
    "payload": {
        "previousDeviceStatus": "Accepted",
        "deviceStatus": "Enrolled",
        "lastUpdatedAt": "1528202916996",
        "deviceUid": "32456783948576",
        "imei": "32456783948576",
        "imei2": "45678898765432"
    }
}

Device relock timestamping

This tutorial demonstrates how you can use Knox Webhook Notification to call the Knox Guard device relock timestamping event and register it with Knox Webhook Notification to receive change notifications when the relock timestamp is applied to the device.

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 “callback” — that you’ll register to receive asynchronous API operation results or event triggers once the event is complete.

3. Register the KG_DEVICE_RELOCK_TIMESTAMP_APPLIED event to asynchronously receive information on the timestamping operation once it’s complete.

Step 2: Update relock timestamp

Update the relock timestamp to the device. Doing so makes an API call to the Knox Guard device relock timestamping operation.

Step 3: Handle response message

After Knox Guard finishes executing the requested operation — relock timestamping — you’ll receive the following message in the body of the subscribed URL call, as the response payload:

{
    "subscriptionId" : "123456789123",
    "event" : "KG_DEVICE_RELOCK_TIMESTAMP_APPLIED",  
    "payload": {
        "relockTimestamp": "1528202916996",
        "lastUpdatedAt": "1528202916996",
        "deviceUid": "32456783948576",
        "imei": "32456783948576",
        "imei2": "45678898765432"
    }
}

Lock a device

This tutorial demonstrates how you can use Knox Webhook Notification to call the Knox Guard device lock event and register it with Knox Webhook Notification to receive change notifications when an enrolled device is locked.

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 once the event is complete.

3. Register the KG_DEVICE_LOCKED event to asynchronously receive the API operation result from the device lock operation once it’s complete.

Step 2: Lock a device

Lock an enrolled device. Doing so makes an API call to the Knox Guard device lock operation.

Step 3: Handle response message

Once the enrolled device is successfully locked, you’ll receive the following message in the body of the subscribed URL call, as the response payload:

{
    "subscriptionId" : "123456789123",
    "event" : "KG_DEVICE_LOCKED",
    "payload": {
        "previousDeviceStatus": "Locking",
        "deviceStatus": "Locked",
        "lastUpdatedAt": "deviceStatus",
        "deviceUid": "32456783948576",
        "imei": "350595220006493",
        "imei2": "45678898765432"
    }
}

Unlock a device

This tutorial demonstrates how you can use Knox Webhook Notification to call the Knox Guard device unlock event and register it with Knox Webhook Notification to receive change notifications when a locked device is unlocked.

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 once the event is complete.

3. Register the KG_DEVICE_UNLOCKED event to asynchronously receive the API operation result from the device unlock operation once it’s complete.

Step 2: Unlock a device

Unlock a locked device. Doing so makes an API call to the Knox Guard device unlock operation, which unlocks the locked device and transitions it back to the normal state (Active).

Step 3: Handle response message

Once the locked device is successfully unlocked, you’ll receive the following message in the body of the subscribed URL call, as the response payload:

{
    "subscriptionId" : "123456789123",
    "event" : "KG_DEVICE_UNLOCKED",
    "payload": {
        "previousDeviceStatus": "Unlocking",
        "deviceStatus": "Enrolled",
        "lastUpdatedAt": "1683023236369",
        "deviceUid": "354387110044347",
        "imei": "350595220006493",
        "imei2": "45678898765432"
    }
}

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);
   

2. 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];
   

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

   String dataToVerify = encodedHeaders + "." + encodedRequestBody;
   

4. 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
       // DO YOUR BUSINESS LOGIC, returns 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.