Event Notifications (webhooks) in Workspace ONE UEM
One of the most understated features of Workspace ONE definitely is Event Notifications. In this post we will go over the topic and its use cases, and a short guide on how to implement it in your environment.
What’s an event notification?
An Event Notification is basically what the name implies. When some “event” happens in Workspace ONE, a notification is being sent to a target URL. Now, this can be used as a very useful trigger for when you want something to happen on a certain event. A very useful event to subscribe on is the Device Enrollment event. Let’s imagine this is all set up and ready to go. What happens when a device enrolls into Workspace ONE is that a JSON message with details about the device will be sent to the target URL. This can be a webserver running PHP listening for notifications. There you can build all kinds of business intelligence that your use case requires.
What can you do with event notifications?
Let’s go over some specific use cases (please comment below if you have some use cases for this in mind).
Use case 1: Populate the Asset Tag for the device
After enrollment an event notification is sent to a server. This starts the process of updating the Asset Tag field in Workspace ONE UEM.
Use case 2: Apply custom tags based on IP range
The device needs to get the correct tags applied to receive its configuration. This is done by a server which receives an event notification when a new device enrolls.
Use case 3: Custom PKI certificate issuing system
A large enterprise customer has a very specific process around their PKI for giving out certificates. This is done by a server which receives an event notification when a new device enrolls.
How to set it up!
Now the most fun part! To set up event notifications and start using it, go to All Settings > System > Advanced > API > Event Notifications. Here you can create a new rule for what should happen on certain events. What I recommend you to do is to go to http://webhook.site, copy your unique URL and add it as a rule. For this test we will enable all events. Like this:
From now on, all events that happen which are enabled will be sent to your unique endpoint on http://webhook.site. Let’s take a closer look at them.
As you can see in this example, an event was sent about a completed enrollment. This is the perfect trigger for any API scripts that need to handle complex configuration which can’t be performed automatically by Workspace ONE UEM itself.
For this post we will implement use case 2: setting a custom tag based on the IP range of the enrolled device. To keep it simple, all of the variables will be kept to a minimum and be contained in the script itself. In any real world scenario, you might want to make it a little bit more versatile.
- Ubuntu virtual machine running Apache and PHP accessible from the Internet
- Workspace ONE UEM
Imagine that we are the UEM Administrator for a company with two sites: Amsterdam and Utrecht. Both sites use their own IP range and thus we want a device enrolling in Amsterdam to receive a different set of profile from a device in Utrecht. For this we could create two tags, which we then link to a smart group.
Step 1: create the custom tags
Go to Groups & Settings > All Settings > Devices & Users > Advanced > Tags. Create a tag called Utrecht and another called Amsterdam. We now want to get the ID of the tags, because later we would need it to assign it to a device. Click on the created tag and note the ID in the url (https://consoleurl.awmdm.com/AirWatch/Tags/Actions/Edit/408460).
Step 2: create the smart groups
Go to Groups & Settings > Groups > Assignment Groups and click Add Smart Group. In the wizard, deselect any ticked checkboxes and filter it down to the tags. Start with SG_Amsterdam and make sure only the tag Amsterdam is selected. And then to the same for SG_Utrecht.
Step 3: create custom profiles
Now we two smart groups that we can use to assign profiles to. Let’s create two iOS profiles with a custom Lock Screen message. The first one will say “Utrecht is the best” and the other one will say “Amsterdam is the best”.
Go to Devices > Profiles & Resources > Profiles and choose Add Profile. Choose iOS and give the profile a name, for example “iOS – Utrecht – Lock Screen”. Choose the smart group which we created in step 2 and configure the Lock Screen Message payload. Repeat this step also for Amsterdam.
Step 4: the fun part!
We have reached the fun part. Scripting! For the script please go to the following Github repo: https://github.com/EUCTechTopics/WS1-Event-Notifications
Make sure that all the variables in the first few lines of the script are configured for your environment. Also make sure that the IP ranges on line 38 and 41 reflect the IP ranges in your environment.
Step 5: serving it to the web
The last part is to setup a webserver that runs PHP, and make it accessible to the Workspace ONE UEM console. I will not go into detail on how to setup a webserver in this post. My recommendation is to run it on Ubuntu. To do so I recommend you to follow this guide on Digital Ocean. If your server is up and running you can upload the script to the web directory and this part is done.
Step 6: the event notification
Go to All Settings > System > Advanced > API > Event Notifications and under the rule for Webhook.site, let’s create another rule. Give it a name, specify the URL to your script, choose JSON instead of XML, and enable the Device Enrollment event. This means that any time a device enrolls, your script will receive the event in JSON format.
Step 7: tryouts!
Now you can enroll a device and see for yourself what happens. When the enrollment completes the script will get the start signal from Workspace ONE UEM. It will ask the Workspace ONE API what the IP address for the giving device ID is, and check based on the two ranges which one is true. If one is true, the Amsterdam tag will be applied. And vice versa if the other one is true, the Utrecht tag will be applied.
Based on these tags a Lock Screen profile (in the case of iOS) will be applied saying either “Utrecht is the best” or “Amsterdam is the best”. This may be a simple example, but the power of this can be far greater. The strength of this solution lies in the fact that it is event driven. Which means that we don’t have to set any schedule to do these types of customisations.
That would normally be the alternative: run a script for example every hour and check all devices and apply tags where needed. First of all this is highly inefficiënt. Second: imagine that the script would run every hour. Now let’s say that the script has just finished running when we enrolled our new device. This would mean that we have to wait at least 59 minutes for the tag to get applied.
I hope that by reading this post you have learned something and I highly encourage you to play around with this. If you have any questions regarding this subject, contact me on the Macadmins Slack where I’ll be happy to help. And last, do comment down below if you know of some use cases which I didn’t mention where an event driven system would be of good use!