Guide to Workspace ONE Webhooks: Features and Best Practices

Workspace ONE UEM can call your endpoint when something happens to a managed device: it enrols, falls out of compliance, is jailbroken or rooted, is wiped or is deleted. Omnissa, which now sells Workspace ONE (formerly VMware AirWatch), calls these Event Notifications. They let a ticketing system, a CMDB or a security tool react to device changes without polling the UEM API.

This guide covers how Event Notifications are configured, the events you can select, how to protect your endpoint with Basic credentials, the gaps in the documentation, and the best practices for production.

What are Workspace ONE webhooks?

An Event Notification is a rule in the UEM console. It names a target URL, a user name and password, a format, and the device events that should trigger a callback. When one of those events happens to a device in the rule's organisation group, Workspace ONE UEM sends a notification to the URL.

Omnissa's page says that "Workspace ONE UEM event notifications use HTTP URLs and basic user authentication method." Notifications aren't signed. The user name and password on the rule are sent as HTTP Basic credentials, and your endpoint checks them.

The documentation is thin. The settings page lists the events by their labels in the console but shows no payload, and it points to an AirWatch API Event Notification Guide for the detail. Plan to capture real notifications from your own tenant before you write any parsing code.

Workspace ONE webhook features

Feature	Details
Where to configure	Groups & Settings > All Settings > System > Advanced > API > Event Notifications
Scope	Per organisation group, with the usual inherit or override settings
Format	JSON or XML, chosen per rule
HTTP method	Not documented. Hookdeck's Workspace ONE source accepts POST
Event identifier	Not documented
Authentication	HTTP Basic, with the user name and password on the rule. No signature
Retries and timeout	Not documented
Source IPs	Not published
Delivery log	ChangeEventOutboundQueueService.Log in the Logs/Services folder of the UEM installation

Common events

The Events section of a rule offers these choices:

Event	Sent when
Check-in/Check-out	A shared device is checked in or out
Device Attribute Change	A selected attribute changes: Asset Number, Device Friendly Name, Device MCC, Ownership, Organization Group ID, Operating System, Phone Number or User Email Address
Device Compliance Status Change	A device's compliance status changes
Device Compromised Status Change	An Android device is rooted or an iOS device is jailbroken
Device Delete	A device is deleted from Workspace ONE UEM
Device Enrollment	A device enrols
Device Unenrolled Enterprise Wipe	A device is enterprise wiped
Device Wipe	A device is wiped

Check-in/Check-out only fires when device event logging is set to Information severity or above, under All Settings > Admin > Events.

These are console labels, not the values that appear in a notification. Omnissa doesn't document how a notification names its event, or which fields describe the device, in either format. Examples you'll find elsewhere, including the ones in our agent skill, use an illustrative EventType field. Treat that as a placeholder until you've seen what your tenant actually sends.

Setting up Workspace ONE webhooks

1. Choose a user name and a long random password for the notification, for example with openssl rand -hex 32. The console describes these as a Workspace ONE UEM user name and password, but any pair your receiver expects will work as Basic credentials, so a dedicated pair is better than a real admin account.
2. In the UEM console, select the organisation group, then go to Groups & Settings > All Settings > System > Advanced > API > Event Notifications and select Add Rule.
3. Enter a Target Name, your HTTPS endpoint as the Target URL, and the User Name, Password and Confirm Password.
4. Choose JSON or XML as the Format. JSON is simpler to route on in most stacks.
5. Select the events you want, including the attributes for Device Attribute Change, and save.

In Hookdeck. Create a source with the Workspace ONE type and enter the same user name and password. Use the source URL as the Target URL. Hookdeck reads the Authorization: Basic header and compares both values. The source accepts POST only. Omnissa doesn't state the method, so check the first notifications in Hookdeck.

Omnissa's docs also don't say whether the Basic credentials are sent with the first request or only after a server answers 401 with a challenge. Hookdeck never sends a challenge, so Workspace ONE has to send the credentials on the first request. Trigger a test event, such as editing a test device's friendly name with Device Attribute Change selected, and confirm it arrives in Hookdeck as an accepted request. If it shows as failed verification instead, the credentials aren't arriving with the request. Check ChangeEventOutboundQueueService.Log on the UEM server, and raise it with Omnissa support, because the rule has no setting that changes this behaviour.

Securing Workspace ONE webhooks

Decode the Authorization header, split it on the first colon, and compare the user name and password with your stored values in constant time.

const crypto = require('crypto');
const express = require('express');

function safeEqual(received, expected) {
  const a = Buffer.from(received, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on buffers of different lengths
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

function verifyBasicAuth(header, user, pass) {
  if (!user || !pass) return false; // fail closed when unconfigured
  const match = /^basic\s+(\S+)\s*$/i.exec(header || '');
  if (!match) return false;
  const decoded = Buffer.from(match[1], 'base64').toString('utf8');
  const i = decoded.indexOf(':'); // the password may contain ':'
  if (i === -1) return false;
  const userOk = safeEqual(decoded.slice(0, i), user);
  const passOk = safeEqual(decoded.slice(i + 1), pass);
  return userOk && passOk;
}

const app = express();

// Raw body, so the handler works whether the rule sends JSON or XML.
app.post('/webhooks/workspace-one', express.raw({ type: '*/*' }), (req, res) => {
  const ok = verifyBasicAuth(
    req.get('authorization'),
    process.env.WORKSPACE_ONE_WEBHOOK_USERNAME,
    process.env.WORKSPACE_ONE_WEBHOOK_PASSWORD
  );
  if (!ok) return res.sendStatus(401);

  const body = req.body.toString('utf8');
  // Store the raw body first; the payload shape isn't documented.
  // Parse JSON or XML once you've captured real notifications.
  res.sendStatus(200);
});

The same check in Python:

import base64
import binascii
import hmac
import re


def verify_basic_auth(header, user, password) -> bool:
    if not user or not password:
        return False  # fail closed
    match = re.fullmatch(r"(?i)basic\s+(\S+)\s*", header or "")
    if not match:
        return False
    try:
        decoded = base64.b64decode(match.group(1), validate=True)
    except (binascii.Error, ValueError):
        return False
    received_user, sep, received_pass = decoded.partition(b":")
    if not sep:
        return False
    user_ok = hmac.compare_digest(received_user, user.encode("utf-8"))
    pass_ok = hmac.compare_digest(received_pass, password.encode("utf-8"))
    return user_ok and pass_ok

Basic credentials prove the sender knows them. They don't prove the body is unchanged, and a captured request can be replayed and still pass, because Workspace ONE sends no signature and no timestamp. Use an HTTPS target URL, keep the password long and random, and change it on the rule and on your receiver together if it leaks.

Make Workspace ONE notifications production-ready. Hookdeck Event Gateway checks the Basic credentials on every notification, stores it, and delivers it to your service with retries and replay.

Workspace ONE webhook limitations and pain points

No documented payload

The Problem: You can't write a parser, or even route by event, from the documentation alone.

Why It Happens: The settings page lists the events by console label and defers payload detail to the AirWatch API Event Notification Guide. Neither the JSON nor the XML body is shown, and no wire value is given for any event.

Workarounds:

• Point a test rule at a capture endpoint, trigger each event you plan to use on a test device, and record the bodies.
• Store every raw body before parsing, so a field you guessed wrong doesn't lose data.
• Ask your Omnissa contact for the Event Notification Guide for your UEM version.

How Hookdeck Can Help: Hookdeck keeps the full headers and body of every notification it receives, so you can inspect real payloads in the dashboard, or with the Hookdeck CLI during development, and build your parser from them.

Unknown delivery guarantees

The Problem: You can't tell from the documentation what happens when your endpoint is slow or down.

Why It Happens: Omnissa documents no timeout, retry policy or ordering. The only delivery detail is the ChangeEventOutboundQueueService.Log file on the UEM server, which on SaaS deployments you may not be able to read.

Workarounds:

• Acknowledge quickly and keep your endpoint highly available, on the assumption that a failed delivery may not be retried.
• Reconcile device state through the UEM REST API on a schedule, so a missed notification is caught.

How Hookdeck Can Help: Hookdeck accepts notifications as they arrive and keeps them, so your service can be down without Workspace ONE seeing a failure. Delivery to your service is retried on Hookdeck's own schedule, and failed deliveries can be replayed once you've fixed the problem.

Basic credentials, with an unknown handshake

The Problem: Notifications fail verification even though the user name and password are right.

Why It Happens: Omnissa doesn't document whether Basic credentials are sent on the first request. A client that waits for a 401 challenge never authenticates against an endpoint that doesn't send one, and Hookdeck doesn't.

Workarounds:

• Test with a single event before relying on the rule.
• If credentials aren't arriving, raise it with Omnissa support.

How Hookdeck Can Help: Hookdeck's Workspace ONE source type checks the Basic user name and password on every request. Hookdeck answers Workspace ONE with a 200 either way, then records a request with missing or wrong credentials as failed verification, so it never reaches your destination, and you can see straight away whether credentials are arriving.

Sensitive device data in transit

The Problem: Notifications can carry user email addresses, phone numbers and device details.

Why It Happens: Device Attribute Change covers fields such as User Email Address and Phone Number, and the payload goes wherever the Target URL points.

Workarounds:

• Use HTTPS only, and select only the events and attributes you need.
• Limit who can read stored notifications, and set a retention period that fits your data policy.

How Hookdeck Can Help: Hookdeck receives notifications over HTTPS and lets you control which destinations each source delivers to, so device data only reaches the services that need it.

Best practices

Capture before you parse

Store the raw body and headers of every notification first, and parse in a background job. Until you've seen real notifications for each event you use, treat any field name as a guess.

Choose one format per receiver

JSON and XML are set per rule. Keep each receiver on one format, and if you must support both, branch on the Content-Type header rather than sniffing the body.

Deduplicate deliveries

No delivery ID is documented. Once you know the payload, build a key from the event, the device identifier and the event time. See our guide to webhook idempotency.

Acknowledge fast and process asynchronously

Return 200 as soon as the notification is stored, and do the work, such as opening tickets or updating an asset register, in a background job. See why to process webhooks asynchronously.

Use a dedicated credential pair

Don't reuse a real UEM administrator's password on the rule. A pair that only exists for notifications can be rotated without touching anyone's console access.

Conclusion

Workspace ONE UEM Event Notifications report device events to a URL you choose, in JSON or XML, protected by Basic credentials rather than a signature. Check those credentials in constant time over HTTPS, confirm they arrive on the first request, and capture real notifications before you rely on any field, because Omnissa's settings page documents no payload and no delivery guarantees.

Hookdeck Event Gateway sits in front of your receiver, checks the Basic credentials, keeps every notification, and delivers it to your service with retries and replay.

Get started with Hookdeck for free and handle Workspace ONE notifications reliably in minutes.