Back to top

Knox Webhook Notification for Knox Device Management Service

Last updated June 26th, 2024

The following tutorials will help you get started with using the Knox Webhook Notification API for Knox Device Management Service.

Currently, the Knox Webhook Notification API supports the following Knox Device Management Service events:

Event Action Description
KDMS_DEVICE_UPLOAD Upload devices Upload a list of devices through Knox Device Management Service.
KDMS_DEVICE_DELETE Delete devices Delete a list of devices through Knox Device Management Service.

Prerequisites

Authentication

You need an authentication token to use Knox cloud services APIs. For more information, see how to get an OAuth 2.0 access token. Make sure you include the kdms.devices scope when you create your OAuth 2.0 app. If you want to provide more granular access permissions, you can grant permission specifically for upload or delete operations with kdms.devices:upload or kdms.devices:delete scopes.

Certificate

Download your Samsung Knox validation certificate. You’ll need the certificate to validate the response you’ll receive from Knox Webhook Notification.

DOWNLOAD CERTIFICATE

Use the Knox Webhook Notification API

Upload devices

This tutorial demonstrates how you can register the event from uploading 10,000 devices to Knox Device Management Service, and register the event with Knox Webhook Notification to receive change notifications when the asynchronous upload operation is complete.

Step 1: Subscribe an event

Subscribe a particular event to Knox Webhook Notification through the Create Subscription operation — POST /kwn/v1/subscriptions. You’ll need to:

  • Provide a subscription URL — known as a “callback” — that you’ll register to receive asynchronous API operation results once the event is complete.

  • Register the KDMS_DEVICE_UPLOAD event to asynchronously receive a result notification once the device upload operation is complete.

Step 2: Upload devices

Upload devices with the Knox Device Management Service API.

Step 3: Handle response message

After the Knox Device Management Service finishes executing the asynchronous operation to upload 10,000 devices, you’ll receive a message in the body of the subscribed URL call as the response payload. You can see the payload schema under Callbacks in the Create subscription operation on the API reference.

Here is an example payload:

One URL for multiple subscriptions

You can also configure one URL across multiple subscriptions. However, you must meet the following conditions:

  • Multiple subscriptions can’t have the same events.

  • The number of subscriptions you can create can’t be more than the number of unique events you can call using Knox Webhook Notification.

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
  1. Prepare the data to verify: DataToVerify = encodedJoseHeader.Base64UrlEncode(HttpRequestPayload)
  1. Decode the signature with Base64Url decoder and verify the data above by using SHA256withRSA

Full code sample

Is this page helpful?