Let’s Git Commit(ted) to Resources: Event Notifications

The Workspace ONE UEM APIs are a great resource for automating tasks, but have you ever found yourself needing to respond to critical device-based events in real-time? Polling information with the APIs on set frequencies to determine if changes have occurred in your environment is inefficient for a number of reasons. It does not allow you to respond in real-time to actions, it requires custom logic to determine which records existed since your last query, and these constant API calls count against your daily API quota. So, what other options do you have?

Event Notifications in Workspace ONE UEM were built for this specific purpose! With Event Notifications, you can receive notifications at an endpoint when important device-based events occur, such as when a device is enrolled, a device check-in/check-out occurs, or a device’s compliance or compromised statuses change. The notification contains a JSON or XML payload with details about the event and allows you to respond in real-time.

Polling vs. Webhooks: What’s the big deal?

Polling refers to the process of constantly querying data on set intervals to confirm if any action is required. Event Notifications, or Webhooks, are instead subscribed to a particular set of actions and are notified when a change has occurred. Compare these two scenarios:

Figure 1: Polling vs. Webhooks

With the polling model, your automation process may need to poll data every few hours or every few minutes, depending on how quickly you need to respond to changes. When polling, you often need to store previous data to compare it against new data to determine if new events have occurred, such as knowing if new devices have enrolled in your organization since your previous check.

Compare this against the Event Notification webhook model, where the configured endpoint receives change notifications directly form Workspace ONE UEM as the subscribed events occur, allowing you to react in real time!

What can I do with Event Notifications?

You can subscribe to several different events to receive notifications for them. Check out the Event Notification docs page or see the table below:

Event	Description
Device Check-in / Check-out	Send a notification when a multi-user device is checked-in or checked-out. In order for multi-user check in / check out notification to function as designed, the device event severity level must be set to Information level or above. You can change this setting by navigating to All Settings / Admin / Events.
Device Attribute Change	Enable to activate the Device Attribute submenu, making it possible to enable individual device identifiers to trigger a notification when they are altered. Supported Attributes Asset Number Device Friendly Name Device MCC Ownership Organization Group ID Operating System Phone Number User Email Address
Device Compliance Status Change	Send a notification when the compliance status of a device changes.
Device Compromised Status Change	Send a notification when the compromised status of a device changes, specifically when an Android is “rooted” or when an iOS device is “jailbroken”.
Device Delete	Send a notification when a device is deleted from Workspace ONE UEM.
Device Enrollment	Send a notification when a device enrolls into either the Workspace ONE Intelligent Hub or Workspace ONE UEM
Device Unenrolled / Enterprise Wipe	Send a notification when a device is unenrolled, or enterprise wiped.
Device Wipe	Send a notification when a device is wiped.

Now that you have the full list of events you can subscribe to, let’s take a deeper dive into a few of these use cases to give you some ideas on how to utilize them.

Use Cases for Device Enrollment

This event allows you to instantly respond to new devices that are enrolled into your organization. This is a great opportunity to automate any organizational tasks, such as:

Tagging: Do you use Device Tags to help track your assets or categorize your devices? The MDM APIs have Device operations that let you add tags to devices, so they are tagged appropriately from day 1 as soon as they enroll.
Change UEM Organization Groups: If your organization group hierarchy is set up for handling multiple physical business locations, you can use the MDM APIs to change which organization group the device is assigned to after enrollment. This can simplify the enrollment process and look up which organization group the device should belong to, based on custom mapping you supply.
External Systems Integration: Do you find yourself syncing your device inventory to other external systems? If so, getting notified of each device enrollment is an excellent time to notify your other systems that a new device is enrolled.

Use Cases for Compliance and Compromised Changes

Compliance and Compromise status changes are important events. Workspace ONE UEM already allows you to respond to non-compliant devices from within the Administration Console but subscribing to these events with Event Notifications allows you to integrate custom solutions beyond what is configurable in the administration console. If you have external systems or processes that you want to notify when these compliance and compromised statuses change, then Event Notifications is a perfect solution.

I’m interested! How do I get started?

To set up Event Notifications, you will need the following:

A web server that can accept POSTs and supports anonymous or basic authentication.
If you intend to call additional Workspace ONE UEM REST APIs from your web server in response to received notifications, you will need an Administrator account and a REST API key configured in the Workspace ONE UEM Administration Console.

Step 1: Set up a Web Server to receive Notifications

Your web server must meet the following requirements:

Figure 2: Web server requirements for Event Notifications

The hosting solution and programming languages used for the web server are up to you, so long as the above requirements are met. Ensure you install any necessary prerequisites for your chosen hosting solution.

Step 2: Workspace ONE UEM Prerequisites

I intend to use additional Workspace ONE UEM REST APIs in response to received notifications, so I need to complete the following prerequisites in the Workspace ONE UEM Administrator Console:

Create an Administrator account with the API Authentication set to User Credentials.

Figure 3: Workspace ONE UEM Admin API Authentication settings
Enable API Access under Groups & Settings > All Settings > System > Advanced > API > REST API. Then copy the AirWatchAPI service API Key provided or create your own API Key for use with your web server.

Figure 4: Workspace ONE UEM REST API settings

Step 3: Create an Event Notification

You can create and edit Event Notifications from Groups & Settings > All Settings > System > Advanced > API > Event Notifications. When adding a rule, you will need to provide:

Target Name: Provide a friendly name to identify this Event Notification.
Target URL: Indicate the endpoint of your web server that will accept the POST command from UEM.
Username / Password: If your web server accepts basic authorization, you will need to provide the credentials here.
Format: Specify if you want to receive the POST payload in JSON or XML format.
Events: Identify the list of events you wish to receive notifications for. All events are marked Disabled by default, so you will need to manually enable each Event you wish to receive.

Figure 5: Creating a Workspace ONE UEM Event Notification

Once you finish configuring the Event Notification and click Save, all future events that you enabled will send a POST to the Target URL with details about the event in either JSON or XML format.

Got any Samples?

Yes, we do! This example will be using an Internet Information Services (IIS) web server and using C# (ASP.NET Core Web APIs). I have installed ASP.NET, configured IIS to accept anonymous authentication, and created an ASP.NET Core Web API project using Visual Studio 2022 Community Edition.

To download the sample, check out the UEM API Event Notification project under the euc-samples GitHub repository.

Overview

An Event Notification has been created and the Device Enrollment event is enabled. When the Device Enrollment event is sent, the following logic is performed:

Check which Organization Group the device belongs to
Query the list of Device tags available at this Organization Group
Tag Windows devices (WinRT) with the “Custom Tag 1” tag
Tag all other devices with the “Custom Tag 2” tag

Figure 6: Event Notification Sample Overview

This simulates an example where we want to apply a tag to device immediately after enrollment, based on some parameters retrieved from the Event Notification; in this case, the platform of the device. This sample provides a foundation for how you can use the data provided with the Event Notification payload, and how to query additional details from Workspace ONE UEM using the REST APIs.

Prerequisites

Windows Server 2012 R2+ or newer
Internet Information Services (IIS) installed
- Basic and/or Anonymous Authentication allowed
ASP.NET Core Hosting Bundle 5.0+ (link here)
Visual Studio 2022 Community Edition
- ASP.NET and web development workload installed
Event Notification GitHub sample cloned or downloaded

Deployment

If you intend to deploy the Event Notification GitHub sample project, follow the below steps to deploy the ASP.NET Web API project to an IIS web server using Visual Studio 2022 Community Edition. If you wish to deploy an Event Notification webhook using another programming language or web server, you can follow these steps as high-level guidance on how to proceed.

1. Internet Information Services (IIS) Web Server Setup

On Windows Server 2012 R2+ or later, use Server Manager to install IIS by selecting Manage > Add Roles and Features > Select Web Server (IIS) under Server Roles to install this role. Be sure to select Basic Authentication for installation under Web Server (IIS) > Web Server > Security > Basic Authentication. Then complete the remaining steps in the Add Roles and Features Wizard by accepting the defaults.

Once IIS is installed, you can open Internet Information Services (IIS) Manager to make the following changes:

If you have an SSL certificate that can be used for your server for HTTPS, you can add the 443 binding by selecting Sites > Default Web Site > Bindings. Click Add on the Site Bindings popup > Select HTTPS for the Type > Select the SSL certificate > OK. If your SSL certificate does not show in the SSL certificate list, you need to install the certificate on the server first.
If you plan to use Basic Authentication, be sure to enable by selecting Sites > Default Web Site > Authentication > Basic Authentication > Enable.

2. ASP.NET Core Hosting Bundle

The Event Notification sample project using ASP.NET Web APIs, so you will need to install the ASP.Net Core Hosting Bundle 5.0+ on your Web Server if not already present. Download and run the installer before proceeding.

3. Visual Studio Setup

Visual Studio 2022 Community Edition is recommended as you can use it to edit, publish, and debug the ASP.NET Web APIs.

Download the Community Edition here and ensure you select the ASP.NET and Web Development workload during installation. Once the installation completes, you will need to reboot.

4. Download and Deploy Event Notification Sample Project

You can either use the Git CLI or a Git client (like GitHub Desktop) to clone the Event Notification GitHub sample project, you can download the repository as a .zip file using Code > Download Zip from the euc-samples repository page.

Once the repository is downloaded locally, open the APIEventNotification.sln file from <project root>\UEM-Samples\Utilities and Tools\Generic\UEM API Event Notifications\APIEventNotification.sln. This will open the solution in Visual Studio 2022.

From Visual Studio, you can deploy the project to the web server by selecting Build > Publish APIEventNotification and make the following configurations:

Target: Web Server (IIS)
Specific target: Web Deploy

Server: http://localhost if using HTTP or https://localhost if using HTTPS
Site Name: Default Web Site
Destination URL: http://localhost/api/webhook or https://localhost/api/webhook if using SSL. You can also use the server URL instead of localhost (i.e.: https://webserver.domain.com/api/webhook)
Username and Password: Credentials for user allowed to publish the project to IIS. In a clean install, you should be able to leave this blank as your current user account will have permission to deploy to IIS. If you have changed the permissions, provide user credentials for an account that can publish to IIS.
Validate Connection: Use to confirm the provided information is valid. Once validated, click Finish.

Your Web Deploy configuration is saved as IISProfile.pubxml and you can click Publish to deploy the project to your web server. There is a GET method configured for /api/webhook, so accessing the page in a browser will return the following if everything is configured correctly:

0: “value1”
1: “value2”

If you close the Publish tab and need to return, you can do so by selecting Build > Publish APIEventNotification in Visual Studio.

5. Event Notification Configuration

The Event Notification sample project is now deployed and ready to integrate with Workspace ONE UEM! Login to the Workspace ONE UEM Administrator Console and navigate to Groups & Settings > All Settings > System > Advanced > API > Event Notifications.

A new Event Notification can be created by clicking Add Rule. Configure the following settings:

Target Name: Provide a friendly name to identify your Event Notification webhook server. You can use the web server URL if desired.
Target URL: Indicate the full URL to your webhook API endpoint, which will be http://{webserver_fqdn}/api/webhook. Specifying /api/webhook is necessary because this endpoint receives the POST command from Workspace ONE UEM. We will discuss this in more detail in an upcoming step.
Username and Password: If using basic authentication, provide the user credentials for your web server. Otherwise, this can remain empty.
Format: If using the Event Notification sample project, select JSON. If using your own solution, select JSN or XML based on your preference.
Test Connection: Use to determine if the server URL is resolvable from Workspace ONE UEM.
Events: If using the Event Notification sample project, enable the Device Enrollment event at the very least. You can enable other events, but the sample project will simply respond with 200 OK to any other event.

When finished, click Save.

6. Workspace ONE UEM API and Tag Configuration

Last step – I promise! The Event Notification uses the Workspace ONE UEM REST APIs to take additional action against devices when they enroll, which we will see shortly. There are two requirements for this to occur:

You will need your Workspace ONE UEM REST API URL, REST API key, and a Workspace ONE UEM administrator account that can authorize the APIs. Check out the previous steps on the Workspace ONE UEM setup if you need help here.
The Event Notification sample uses two tags: “Custom Tag 1” and “Custom Tag 2”, so these must be setup in your organization group first. You can create each tag by going to Groups & Settings > All Settings > Devices & Users > Advanced > Tags > Create Tag.

Walkthrough

There are two files in the project that we will review:

Controllers\UEMAPIController.cs: Handles the Workspace ONE UEM REST API setup and communication to query additional details and tag the devices.
Controllers\WebhookControllers.cs: Receives the POST request and payload from Workspace ONE UEM when subscribed events are triggered.

To start, you will need to replace the UEM API information in UEMAPIController.cs and publish to IIS:

public static readonly string UEM_API_URL = “https://{UEM API URL}/api/”;
public static readonly string UEM_API_USERNAME = "{UEM ADMIN USERNAME}";
public static readonly string UEM_API_PASSWORD = "{UEM ADMIN PASSWORD}";
public static readonly string UEM_API_KEY = "{UEM API KEY}";

WebhookController.cs receives the POST request which is processed in the Post() method:

[HttpPost]
public async Task<IActionResult> Post(dynamic json)
{
    JObject jObj = JObject.Parse(json.ToString());
    string eventType = jObj["EventType"].Value<string>()
    IActionResult result = null;

    switch (eventType)
    {
        case "Enrollment Complete":
            result = await HandleDeviceEnrollment(jObj);
            break;

        default:
            result = Ok();
            break;
    }

    return result;
}

This method achieves the following logic:

When the POST request is received, serialize the JSON payload into a JObject type
Store the EventType property of the JSON payload as a string. If more than one Event is subscribed to, this is critical so you can determine which action you are responding to.
The switch case evaluates what logic should run based on the EventType property. If the Event Type is “Enrollment Complete” (the Device Enrollment event), then the HandleDeviceEnrollment() method will be called. Otherwise, all unhandled events respond with 200 OK.

The HandleDeviceEnrollment() method is as follows:

private async Task<IActionResult> HandleDeviceEnrollment(JObject json)
{
    try
    {
        // Enrollment Complete event received - get the full device details
        int deviceID = json["DeviceId"].Value<int>();
        JObject deviceJSON = await UEMAPIController.GetDeviceByID(deviceID);

        // Search for applicable tags in this organization group
        int enrolledGroupId = deviceJSON["LocationGroupId"]["Id"]["Value"].Value<int>();
        List<JObject> availableTags = await UEMAPIController.SearchTagsAtOrgGroupID(enrolledGroupId);

        // Apply a tag to the enrolled device based on some logic
        // In this case, all Windows 10 (WinRT) devices get Custom Tag 1 and all other deice types get Custom Tag 2
        string devicePlatform = deviceJSON["Platform"].Value<string>();
        string desiredTagName = string.Empty;
        switch (devicePlatform)
        {
            case "WinRT":
                desiredTagName = "Custom Tag 1";
                break;

            default:
                desiredTagName = "Custom Tag 2";
                break;
        }
        JObject tagJSON = availableTags.Find(x => x["TagName"].Value<string>() == desiredTagName);
        int tagID = tagJSON["Id"]["Value"].Value<int>();
        bool didAddTag = await UEMAPIController.AddDeviceToTag(tagID, deviceID);

        if (didAddTag)
            return Ok();
        else
            return NotFound();
    }
    catch (Exception ex)
    {
        // If an exception occurs, report as a 500 response with the exception message and payload body
        return Problem(ex.Message, json.ToString(), 500);
    }
}

The HandleDeviceEnrollment() method achieve the following logic:

Obtain the DeviceID from the POST request JSON payload. This is the DeviceID of the device that just enrolled.
Use the UEM APIs to query more information about the device (UEMAPIController.GetDeviceByID({id}))
Get the Organization Group ID from the GetDeviceByID({id}) response and get a list of available tags at this Organization Group (UEMAPIController.SearchTagsAtOrgGroupID{id})
If the device’s platform is WinRT (Windows), tag it with the “Custom Tag 1” tag. Otherwise, tag it with the “Custom Tag 2” tag.
Tag the device with the desired tag (UEMAPIController.AddDeviceToTag({tagID}, {deviceID}))
Return either a 200 OK if everything succeeds, a 404 NotFound if the device couldn’t be tagged (ie: missing Tag), or a 500 Server Error with the exception message if an error occurs.

If you wish to see the inner workings of the UEM API communication, check out each of the UEMAPIController methods that are used to see which UEM APIs are leveraged and how the requests are formed!

This sample shows how you can build a custom workflow to tag devices as soon as they are enrolled by leveraging the Event Notification to respond in real-time and the UEM APIs to perform additional actions when the device finishes enrolling.

Putting it all together!

To test, you will need to enroll a device in the organization group where your Event Notification is configured, and the “Custom Tag 1” and “Custom Tag 2” device tags exist. Once a device enrolls, the device will be tagged with “Custom Tag 1” if it is a Windows device and “Custom Tag 2” for any other device type. Go ahead and enroll a device and try it out!

Figure 7: Devices List View with Custom Tag

You can also debug the webhook to see what is happening step-by-step with Visual Studio. To do so, open Visual Studio and select Debug > Attach to Process > w3wp.exe > Attach. You can then add “breakpoints” to the WebhookController.cs and UEMAPIController.cs files using Debug > Toggle Breakpoint or the F9 key.

NOTE: If you do see w3wp.exe in the available processes list, you may need to check Show processes for all users.

Resources

Interested in learning more? Check out these great resources!

Conclusion

Workspace ONE UEM Event Notifications are a powerful framework to enable real-time responses to critical events in your device fleet and allows you to build custom workflows to integrate with VMware EUC solutions or third-party solutions. Consider how Event Notifications and the webhook model can reduce your manual polling and enable real-time responses for critical events for your use cases!

If you found this resource useful, be sure to subscribe to the Digital Workspace Tech Zone Blog RSS and follow us on Twitter @EUCTechZone to stay updated on the latest EUC content!

Agenda

Make sure to check out the other blog posts in our 28-day series:

Day 1: Let's Git Commit(ted) to Dev Resources
Day 2: Getting Started with the Workspace ONE UEM REST APIs
Day 3: Getting Started with the Workspace ONE Access APIs
Day 4: Getting Started with the VMware Workspace ONE Intelligence APIs
Day 5: Getting Started with the VMware Horizon REST APIs and VMware PowerCLI
Day 6: Getting Started with Automating the Unified Access Gateway Deployment
Day 7: Podcast: Day 0 Onboarding Automation with Scot Curry
Day 8: Video: Anatomy of the Workspace ONE UEM API
Day 9: Introduction to using Postman - Part 1
Day 10: Introduction to using Postman - Part 2
Day 11: Pro Tips and Tricks - How to be an API Boss
Day 12: What is OAuth - Learning the Basics
Day 13: Getting Started with Intelligent Hub Notifications
Day 14: Git Basics: Getting Git Going
Day 15: Podcast: Git Commit(ted) to Resources: Customer Spotlight with The Home Depot
Day 16: Git VMware {code} Samples and Flings
Day 17: Using paginated requests with Workspace ONE UEM REST APIs
Day 18: Event Notifications
Day 19: Overview of Script Samples using PowerCLI for Horizon
Day 20: Uploading Windows apps using REST APIs
Day 21: Uploading macOS apps using REST APIs and Admin Assistant
Day 22: API-based user lifecycle and SCIM
Day 23: Video: Community Expert Roundtable on Leveraging APIs and Scripting
Day 24: Video: Exploring the Workspace ONE GitHub Samples Repository
Day 25: Featured Fling: Forklift for Workspace ONE UEM
Day 26: Featured VMware {code} Samples for Horizon
Day 27: Featured Flings for VMware Horizon
Day 28: Continuing to Focus on </Dev> Resources Page

Let’s Git Commit(ted) to </Dev> Resources: Event Notifications