Applies to: HealthPro

Summary

This article explains how to forward HealthPro device events to a third-party ITSM system, ServiceNow, in real time using HealthPro Webhooks.

NOTE: Webhooks support ServiceNow endpoints only for security and performance.

IMPORTANT: Only Manager or higher roles can configure Webhooks.

License gating is preserved: if a device requires a HealthPro license for task 
creation and does not have it, its events are not sent to third parties.

When Webhooks are on: 

• HealthPro stops creating and storing Tasks (Notification Center, Task logs) for the selected events and instead sends them to ServiceNow in real time.
   
• Existing Tasks created before enabling webhooks remain visible and actionable.
   
• Health logs continue to be recorded in HealthPro.
   
• UI notice in Notification Center: “Task creation and logging are disabled because sending device events to third parties is enabled.”

Connecting Webhooks

To enable and connect Webhooks:

1. Log in to Cloud Portal and click HealthPro. 
    

2. Navigate to Settings > 3rd Party Integration > Webhook.
    

    

3. Toggle Webhook to On.

   When toggled on, nothing appears in HealthPro Tasks. This is expected.
   
    

4. For Authentication method: API Key (fixed)
    
5. For Authentication key value: copy and paste your key.
    
6. For the Target URL: use your ServiceNow HTTPS endpoint. 
   
   Example: https://dev-12345.service-now.com/api/...
    

7. Select event types to send (all selected by default; see Supported events). 

   If the key and URL are valid, and target is allow-listed, a success toast appears.
   
   If invalid or not allow-listed, the application fails and your inputs remain on screen.

If the configuration fails:

• Verify the Target URL uses HTTPS.
• Verify the endpoint is under an allow-listed domain.
• Verify the API key is correct.

NOTE: When you toggle Off, all previously entered Webhook values are cleared 
(warning pop‑up appears).

Controlling Event Volume (duplicate suppression and delay)

To avoid duplicates and delays: 

• Avoid sending duplicate events.

  Default: Enabled.

  Rule: If less than 48 hours have passed since an event (of any type) from the same device was sent to a third party, a new event for the same device is not sent.

  Tooltip: “If less than 48 hours have passed since an event was sent to a third party from the same device, events will not be sent to the same device.”

  When disabled: Events can be sent immediately and repeatedly (previous 48‑hour suppressions remain as applied).
   

• Send a delayed event.

  Default: Enabled.

  Rule: For device offline/failure‑like events, HealthPro rechecks device status after 24 hours; only if the device is still in the same state, the event is sent. The event timestamp corresponds to the recheck time.

  Camera Disconnected

  Server Failure

  Device Disconnected (PoE switch)

  Network Issue

  If the device is back to Good/Online at recheck, the event is canceled.

  Any additional occurrences of the four event types within the 24‑hour delay window are ignored.

  When disabled: Events are sent immediately (existing in‑flight delayed items are not changed).

NOTE: If no incidents are created in ServiceNow, confirm API key validation,
endpoint path, and that Webhooks are On with the correct events selected. 
Check if 48‑hour duplicate suppression or 24‑hour delay is active.

Verify Events in ServiceNow

• Map incoming Webhook events (see Payload spec below) to Incident/Event/Alert tables in ServiceNow.
   
• Use eventId for idempotency and updates.
   
• Use organization/location/area/gateway fields for CI/Location relationships.
   
• Update existing records on repeated events rather than creating new records.
  
  

Payload specification (Operator summary)

All Webhook messages use HTTP POST with JSON body and API key header.

POST {Target URL}
Content-Type: application/json
X-HP-API-KEY: <authentication_key>
 

Envelope (versioned):
{
 "specVersion": "1.0",
 "eventId": "uuid",
 "eventType": "string",
 "occurredAt": "ISO-8601 timestamp",
 "source": "healthpro",
 "data": {
   "organizationId": "uuid",
   "locationId": "uuid",
   "locationName": "string",
   "areaId": "uuid (optional)",
   "areaName": "string (optional)",
   "gatewayDeviceId": "uuid",
   "gatewayDeviceName": "string",
   "eventDeviceId": "uuid",
   "eventDeviceName": "string",
   "eventDeviceType": "ipcam|waveCamera|dmserver|nwc...",
   "modelName": "string",
   "ipAddress": "string",
   "macAddress": "string",
   "eventType": "string (e.g., cameraDisconnectEvent)",
   "errorCode": 1001,
   "description": "string"
 }
}

Response codes:

• Success: HTTP 200 OK or 204 No Content
• Typical errors: 400 (bad payload), 401 (invalid API key), 403, 500

Retry: Current version sends once (no automatic retries). Consider designing a resilient ServiceNow endpoint.

Supported events (specVersion 1.0)

• Camera Disconnected → cameraDisconnectEvent
• Camera IP Conflict → cameraIpConflictEvent
• License Issue → licenseIssueEvent
• Network Issue → networkIssueEvent
• Server Certificate Error → serverCertificateError
• Server Conflict → serverConflictEvent
• Server Failure → serverFailureEvent
• Server Started → serverStartEvent (currently disabled)
• Storage Issue → storageFailureEvent
• Device Disconnected (PoE switch) → deviceDisconnectEvent
• Image Health Issue → imageHealthIssueEvent

UI Parity

Available/visible event options in HealthPro UI follow the Task creation options. If a type is not supported for Tasks, exclude it from Webhook selection.

Audit Trail (User logs)

• Category: Webhook
   
• Auto (enabled): detail “On: Enabled webhooks - Events & tasks.”
   
• Canceled (disabled): detail “Off: Disabled webhooks - Events & tasks.”
   
• User logs CSV exports include the new category/details; a Webhook filter is available in User logs.

Security Best Practices

• Validate X-HP-API-KEY on every request and never log it in plain text.
   
• Serve HTTPS only; consider IP allow‑list and rate limiting on ServiceNow side.
   
• Use eventId for idempotency to prevent duplicates.