Back to top

Knox Webhook Notification for Knox E-FOTA

Last updated October 15th, 2024

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

Currently, the Knox Webhook Notification API supports the following Knox E-FOTA events:

Event Action Description
KE_DEVICE_BULK_CREATE Bulk upload Allows bulk upload of devices.
KE_DEVICE_BULK_REFRESH Bulk refresh Forces the Knox E-FOTA client app to refresh on multiple devices.
KE_DEVICE_BULK_DELETE Bulk deletion Allows bulk deletion of devices.
KE_CAMPAIGN_DELETE Campaign deletion Deletes an existing Knox E-FOTA campaign.
KE_DEVICE_STATUS_CHANGE Device status change Change in device status (operation or client status).
KE_DEVICE_BULK_LICENSE_UNENROLL Bulk license unenrolling Bulk license unerolling of devices.

Prerequisites

Authentication

To start using Knox E-FOTA APIs, you need an authentication token. The way to obtain a token depends on whether you are a Knox customer or an EMM provider. For more information, see:

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

Upload devices

This tutorial demonstrates how you can use Knox Webhook Notification to call the Knox E-FOTA upload devices event to bulk upload 10,000 devices, and register the event with Knox Webhook Notification to receive change notifications when the upload 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 KE_DEVICE_BULK_CREATE event to asynchronously receive the API operation result on the device upload API operation once it’s complete.

Step 2: Upload a device

Upload the devices. The upload operation makes an API call to the Knox E-FOTA upload devices operation.

Step 3: Handle response message

After Knox E-FOTA finishes executing the requested operation — uploading of 10,000 devices — you’ll receive the following message in the body of the subscribed URL call as the response payload:

Multiple upload events

You can use the same Knox Webhook Notification subscription with multiple bulk device upload events, as follows:

  • You must set the X-WSM-TXID header when you call the Knox E-FOTA bulk device upload API operation.
  • Once the API operation is complete, Knox E-FOTA will pass the value of X-WSM-TXID to Knox Webhook Notification.
  • Then, Knox Webhook Notification will assign the value of X-WSM-TXID to the X-WSM-TRACEID header when calling the Knox Webhook Notification callback URL.

Currently, you must use the Knox E-FOTA X-WSM-TXID header from the Knox E-FOTA API, and the Knox Webhook Notification X-WSM-TRACEID header.

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

    verify(DataToVerify, Base64UrlDecode(Signature))

Complete code

One URL for multiple subscriptions

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

  • No API calls are made to the same event more than once, that is, the events must be unique across all your subscriptions.

  • The number of subscriptions you can create can at most be equal to the number of unique events you can call using Knox Webhook Notification.

As a customer, the maximum number of subscriptions you create should be equal to the number of unique events you can call using Knox Webhook Notification. Check out release notes for a list of all the events that Knox Webhook Notification currently supports.

For EMMs with multiple customers

Knox Webhook Notification also supports EMMs that will make API calls to the Knox E-FOTA API on behalf of customers. You can make multiple subscriptions either by configuring a separate URL for each subscription or using the same URL across all subscriptions.

One URL per subscription

You can configure one URL while creating a subscription, as follows:

  1. Use companyA to create the subscription using the Knox Webhook Notification Subscription API.
  2. Configure example.com/kwn_result/companyA as the callback URL.
  3. Make a call to one of the supported events using the same callback URL.

Once you successfully complete these steps, the configured URL example.com/kwn_result/companyA will receive the operation result.

Similarly, after repeating all the aforementioned steps for companyB, example.com/kwn_result/companyB will receive the operation result for a different subscription associated with companyB.

Is this page helpful?