# Manage Engine OpManager Integration ### Overview This guide walks you through integrating ManageEngine OpManager with our alert management platform. OpManager delivers alert notifications through its **Notification Profile** system using the **Invoke a Webhook** profile type. When a device threshold is violated or a device becomes unreachable, OpManager sends an HTTP POST payload to the configured webhook URL. When the alarm clears (condition returns to normal), OpManager sends a separate payload with `severity: "Clear"` for recovery. ### Integration Flow 1. OpManager continuously monitors device health, performance metrics, and availability via SNMP/WMI/CLI. 2. When a threshold is violated or a device becomes unreachable, OpManager generates an alarm. 3. The Notification Profile evaluates its criteria (severity, category, device) and sends an HTTP POST webhook payload to the configured endpoint. 4. When the condition returns to normal, OpManager sends a **Clear** alarm using the same `alarm_id` for lifecycle correlation. ### Webhook Payload Schema OpManager does **not** provide a predefined webhook payload format. A custom JSON structure must be manually configured inside the Notification Profile's body content using OpManager's built-in message variables. Below is the recommended payload template to paste into the webhook body content: ```json { "alarm_id": "$alarmid", "severity": "$stringseverity", "device_name": "$displayName", "ip_address": "$DeviceField(ipAddress)", "message": "$message", "category": "$category", "event_type": "$eventType", "entity": "$entity", "last_polled_value": "$lastPolledValue", "device_type": "$DeviceField(type)", "timestamp": "$strModTime" } ``` #### Payload Fields | Field | Variable | Type | Required | Description | | ------------------- | ------------------------- | ------ | -------- | ---------------------------------------------------------------- | | alarm\_id | `$alarmid` | string | Yes | Unique alarm identifier for lifecycle correlation | | severity | `$stringseverity` | string | Yes | Alarm severity level (Critical, Trouble, Attention, Clear, etc.) | | device\_name | `$displayName` | string | Yes | Display name of the affected device | | ip\_address | `$DeviceField(ipAddress)` | string | No | IP address of the affected device | | message | `$message` | string | Yes | Human-readable alarm description | | category | `$category` | string | Yes | Alarm category (e.g., Server, Router, Switch, Firewall) | | event\_type | `$eventType` | string | Yes | Event type indicating trigger or recovery (see table below) | | entity | `$entity` | string | No | Specific monitored entity (e.g., CPU, Disk, Interface name) | | last\_polled\_value | `$lastPolledValue` | string | No | Last polled metric value that triggered the alarm | | device\_type | `$DeviceField(type)` | string | No | Device type classification in OpManager | | timestamp | `$strModTime` | string | Yes | Alarm timestamp in OpManager's configured format | > **Note:** All values are resolved at the time OpManager sends the webhook. When using **Test Action** in the Notification Profile, message variables will be sent as literal strings (e.g., `$message`) since there is no real alarm context. *** ### Severity Mapping | OpManager Severity | Platform Status | Description | | ------------------ | --------------- | ---------------------------------------------- | | Critical | PROBLEM | Major outage or serious service degradation | | Trouble | PROBLEM | Performance degradation requiring action | | Attention | PROBLEM | Warning condition close to threshold violation | | Service Down | PROBLEM | Device or service is completely unreachable | | Clear | RECOVERY | Alarm has recovered, service is back to normal | > **Note:** The `Unmanaged` device status does not generate webhook alarms. A device must be in `Managed` state for alarms to be raised. Reference: [Alarm Severity Levels in OpManager](https://pitstop.manageengine.com/portal/en/kb/articles/alarm-severity-levels-in-opmanager) ### Event Types OpManager uses the `eventType` field to indicate what triggered the alarm: | Event Type | Direction | Description | | -------------- | --------- | ------------------------------------------------------ | | Threshold Down | Trigger | A performance metric exceeded its configured threshold | | Threshold Up | Recovery | A performance metric returned to normal | | Device Down | Trigger | Device stopped responding (availability failure) | | Device Up | Recovery | Device is back online and responding | ### Alert Payload Examples #### Performance Alarm — CPU Utilization **Raised (Critical)** This payload is sent when a performance metric (e.g., CPU utilization) exceeds its configured threshold. ```json { "alarm_id": "2", "severity": "Critical", "device_name": "prod-web-server-01", "ip_address": "10.0.1.40", "message": "CPU Utilization is 100%, threshold value for this monitor is 90%: Top 3 Processes:-stress - 99.8%;stress - 99.8%;stress - 99.8%", "category": "Server", "event_type": "Threshold Down", "entity": "CPU Utilization", "last_polled_value": "100", "device_type": "Server", "timestamp": "27 Oct 2025 02:36:21 PM" } ``` **Cleared** This payload is sent when the CPU utilization returns below the threshold. The `severity` is `Clear` and the `event_type` is `Threshold Up`. ```json { "alarm_id": "2", "severity": "Clear", "device_name": "prod-web-server-01", "ip_address": "10.0.1.40", "message": "CPU Utilization is now back to normal, current value is 0%", "category": "Server", "event_type": "Threshold Up", "entity": "CPU Utilization", "last_polled_value": "0", "device_type": "Server", "timestamp": "27 Oct 2025 02:37:20 PM" } ``` #### Availability Alarm — Device Down **Raised (Attention)** This payload is sent when a device stops responding to health checks. ```json { "alarm_id": "1", "severity": "Attention", "device_name": "prod-web-server-01", "ip_address": "10.0.1.40", "message": "Device not responding: Probably down or busy", "category": "Server", "event_type": "Device Down", "entity": "", "last_polled_value": "", "device_type": "Server", "timestamp": "27 Oct 2025 02:43:59 PM" } ``` **Cleared** This payload is sent when the device comes back online. ```json { "alarm_id": "1", "severity": "Clear", "device_name": "prod-web-server-01", "ip_address": "10.0.1.40", "message": "Device Active and Responding", "category": "Server", "event_type": "Device Up", "entity": "", "last_polled_value": "", "device_type": "Server", "timestamp": "27 Oct 2025 02:53:54 PM" } ``` ### Installation & Configuration #### Step 1: Create an Alert Source in the Platform 1. Log in to the alert management platform. 2. Navigate to **Integrations** → **Add Integration**. 3. Select **OpManager** as the provider. 4. Name the integration (e.g., `Production OpManager Alerts`). 5. Save and copy the generated **Webhook URL** and **Token**. #### Step 2: Create a Webhook Notification Profile in OpManager 1. Log in to your **OpManager** web console. 2. Navigate to **Settings** → **Notifications** → **Notification Profiles**. 3. Click **Add** to create a new notification profile. 4. Select **Invoke a Webhook** as the profile type. #### Step 3: Configure the Webhook Settings 1. Set the following fields: * **HTTP Method**: `POST` * **Hook URL**: Paste your platform webhook URL * **Data Type**: `raw` * **Payload Type**: `JSON` * **Content-Type**: `application/json` 2. Add a custom HTTP header for authentication: * **Header Name**: `x-itoc-360` * **Header Value**: `Bearer ` 3. In the **Body Content** field, paste the following JSON payload template: ```json { "alarm_id": "$alarmid", "severity": "$stringseverity", "device_name": "$displayName", "ip_address": "$DeviceField(ipAddress)", "message": "$message", "category": "$category", "event_type": "$eventType", "entity": "$entity", "last_polled_value": "$lastPolledValue", "device_type": "$DeviceField(type)", "timestamp": "$strModTime" } ``` 4. Click **Next**.
#### Step 4: Configure Notification Criteria 1. Select the alarm criteria that should trigger this webhook: * ✅ **Device Down alarms** * ✅ **Threshold-based alarms** (performance monitors) * ✅ Any other relevant alarm categories 2. **⚠️ CRITICAL:** Check the **"Notify when the alarm is cleared"** checkbox. Without this, recovery (Clear) payloads will not be sent and alerts will never auto-resolve.
3. Select all **Severity** levels you want to be notified for: * ✅ Critical * ✅ Trouble * ✅ Attention * ✅ Service Down 4. Click **Next**.
#### Step 5: Associate Devices 1. Under **Available Devices**, select the devices you want to monitor with this webhook. 2. Move them to the **Selected Devices** column using the right arrow. 3. Click **Next**. > **Tip:** You can also associate the profile with **Device Groups** or **Interface Groups** instead of individual devices.
#### Step 6: Configure Time Window 1. Choose when this profile should be active: * **Apply this profile 24x7** (recommended for production monitoring) * Or specify a custom time window (e.g., business hours only) 2. Click **Next**.
#### Step 7: Save and Test 1. Enter a **Profile Name** (e.g., `OnCall Platform Webhook`). 2. Click **Test Action** to verify the webhook is reachable. > **Note:** When using Test Action, OpManager sends the payload with message variables as literal strings (e.g., `$message` instead of the actual alarm message). This is expected behavior — variables are only resolved during real alarm events. 3. Click **Save** to enable the notification profile.\
### Testing #### Trigger a Performance Alarm To validate the integration, trigger a test alarm: 1. Force a CPU or memory threshold breach on a monitored device (e.g., run a stress test). 2. Verify that a webhook payload with `severity: "Critical"` (or `"Trouble"`) and `event_type: "Threshold Down"` is received at your platform endpoint. #### Trigger a Device Down Alarm 1. Disconnect a monitored device from the network or stop responding to SNMP/ICMP. 2. Verify that a webhook payload with `event_type: "Device Down"` is received. #### Verify Recovery (Clear) 1. Resolve the threshold breach or bring the device back online. 2. Verify that a webhook payload with `severity: "Clear"` and the matching `alarm_id` is received. #### Verification Checklist Verify that: 1. A **raised** alarm payload is received by the platform (status: PROBLEM). 2. The `alarm_id`, `severity`, `device_name`, and `message` fields are populated correctly. 3. A **Clear** alarm payload is received after recovery (status: RECOVERY). 4. The `alarm_id` matches between raised and cleared payloads for proper lifecycle correlation. 5. The `event_type` correctly reflects the alarm type (`Threshold Down`/`Threshold Up`, `Device Down`/`Device Up`). #### Webhook Delivery Logs To check delivery status within OpManager: Navigate to **Settings** → **Notifications** → **Notification Profiles** → Click the **View Report** icon (in the Actions column) for your webhook profile. ### Troubleshooting | Issue | Possible Cause | Resolution | | ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------ | | No alerts received | Webhook profile not enabled or not assigned | Verify the profile is saved and associated with the correct devices | | No alerts received | Criteria not matching | Check that the correct alarm types and severity levels are selected in the notification criteria | | Clear/recovery alerts missing | "Notify when alarm is cleared" not checked | Edit the notification profile and enable the **Notify when the alarm is cleared** checkbox | | Incorrect payload structure | Missing or incorrect variables | Apply the exact payload template provided in this document with correct OpManager variables | | Authentication error (401/403) | Authorization header missing or incorrect | Verify the `Authorization: Bearer ` header is set correctly in the webhook profile | | No alarms during downtime | Device state is Unmanaged | Change the device back to **Managed** state in OpManager | | Variables sent as literal text | Using Test Action | This is expected — variables are only resolved during real alarm events, not during test actions | | Delayed notifications | Time window restricting delivery | Verify the notification profile is set to **Apply this profile 24x7** or adjust the time window | | Duplicate notifications | Multiple profiles matching same device | Review notification profiles and ensure each device is assigned to only one webhook profile | ### FAQ **Are alerts automatically resolved?** Yes, when an alarm clears in OpManager, a payload with `severity: "Clear"` and the same `alarm_id` is sent automatically, provided the **"Notify when the alarm is cleared"** option is enabled in the notification profile. **Can I monitor different device groups with different webhook endpoints?** Yes, create separate webhook Notification Profiles for each group and associate them with the appropriate devices or device groups. **Which operating systems does OpManager support?** OpManager **server** (the management console) runs on Windows and Linux. However, OpManager can **monitor** devices running any operating system — including macOS, Windows, Linux, and network appliances — via SNMP, WMI, SSH/CLI, and other protocols. **What happens if the webhook endpoint is unreachable?** OpManager will log a delivery failure. You can check the delivery status in the Notification Profile's View Report section. OpManager does not retry failed webhook deliveries by default, so ensure your endpoint is highly available.