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.

Webhooks

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.
    
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.

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: 

1. 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).

2. 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).

Verifying 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.

Troubleshooting

• Apply failed: Verify the Target URL is an HTTPS endpoint under an allow‑listed domain and the API key is correct.
   
• No incidents 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.
   
• Nothing appears in HealthPro Tasks: This is expected while Webhooks are On; check Notification Center banner.