적용 대상: HealthPro

요약

이 문서에서는 HealthPro Webhooks를 사용하여 HealthPro 장치 이벤트를 타사 ITSM 시스템인 ServiceNow로 실시간 전달하는 방법을 설명합니다.

참고: 보안 및 성능을 위해 Webhooks는 ServiceNow 엔드포인트만 지원합니다.

중요: Manager 이상 역할만 Webhooks를 구성할 수 있습니다.

라이선스 제한이 적용됩니다. 작업 
생성에 HealthPro 라이선스가 필요한 장치에 해당 라이선스가 없으면 해당 이벤트는 타사로 전송되지 않습니다.

Webhooks가 켜져 있으면:

HealthPro는 선택한 이벤트에 대해 작업(Notification Center, 작업 로그)을 생성하고 저장하는 대신 ServiceNow로 실시간 전송합니다.
Webhooks를 활성화하기 전에 생성된 기존 작업은 계속 표시되며 조치를 취할 수 있습니다.
Health 로그는 계속 HealthPro에 기록됩니다.
Notification Center의 UI 알림: “타사로 장치 이벤트를 전송하는 기능이 활성화되어 작업 생성 및 로깅이 비활성화되었습니다.”

Webhooks 연결

Webhooks를 활성화하고 연결하려면 다음을 수행합니다.

Cloud Portal에 로그인하고 HealthPro를 클릭합니다.
Settings > 3rd Party Integration > Webhook으로 이동합니다.
Webhook 을 On으로 전환합니다.

켜면 HealthPro Tasks에 아무것도 표시되지 않습니다. 이는 정상적인 동작입니다.
Authentication method: API Key (fixed)
Authentication key value: 키를 복사하여 붙여 넣습니다.
Target URL: ServiceNow HTTPS 엔드포인트를 사용합니다.

예: https://dev-12345.service-now.com/api/...
전송할 이벤트 유형을 선택합니다(기본적으로 모두 선택되어 있음. 지원되는 이벤트 참조).

키와 URL이 유효하고 대상이 허용 목록에 있으면 성공 토스트가 표시됩니다.

유효하지 않거나 허용 목록에 없으면 애플리케이션이 실패하고 입력한 내용은 화면에 유지됩니다.

구성에 실패한 경우:

Target URL에서 HTTPS를 사용하는지 확인합니다.
엔드포인트가 허용 목록에 있는 도메인에 속하는지 확인합니다.
API 키가 올바른지 확인합니다.

참고: Off로 전환하면 이전에 입력한 모든 Webhook 값이 삭제됩니다. 
(경고 팝업이 표시됩니다.)

이벤트 볼륨 제어(중복 억제 및 지연)

중복 및 지연을 방지하려면:

중복 이벤트 전송을 방지합니다.

기본값: 활성화됨.

규칙: 동일한 장치에서 발생한 이벤트(유형 무관)가 타사로 전송된 후 48시간이 지나지 않은 경우 동일한 장치에 대한 새 이벤트는 전송되지 않습니다.

툴팁: “동일한 장치에서 이벤트가 타사로 전송된 후 48시간이 지나지 않은 경우 해당 장치로 이벤트가 전송되지 않습니다.”

비활성화한 경우: 이벤트를 즉시 반복해서 전송할 수 있습니다(이전에 적용된 48시간 억제는 계속 적용됨).
지연된 이벤트를 전송합니다.

기본값: 활성화됨.

규칙: 장치 오프라인/장애 유형 이벤트의 경우 HealthPro는 24시간 후 장치 상태를 다시 확인합니다. 장치가 여전히 동일한 상태인 경우에만 이벤트가 전송됩니다. 이벤트 타임스탬프는 재확인 시간에 해당합니다.

카메라 연결 끊김

서버 장애

장치 연결 끊김(PoE 스위치)

네트워크 문제

재확인 시 장치가 정상/온라인 상태로 돌아온 경우 이벤트가 취소됩니다.

24시간 지연 시간 동안 발생하는 위 네 가지 이벤트 유형의 추가 발생은 무시됩니다.

비활성화한 경우: 이벤트가 즉시 전송됩니다(이미 처리 중인 지연 항목은 변경되지 않음).

참고: ServiceNow에서 인시던트가 생성되지 않는 경우 API 키 검증, 엔드포인트 경로, 
그리고 올바른 이벤트가 선택된 상태에서 Webhooks가 On인지 확인합니다. 
48시간 중복 억제 또는 24시간 지연이 활성화되어 있는지 확인합니다.

ServiceNow에서 이벤트 확인

수신된 Webhook 이벤트(아래 Payload 사양 참조)를 ServiceNow의 Incident/Event/Alert 테이블에 매핑합니다.
멱등성 및 업데이트에 eventId를 사용합니다.
CI/Location 관계에 organization/location/area/gateway 필드를 사용합니다.
반복 이벤트가 발생하면 새 레코드를 생성하는 대신 기존 레코드를 업데이트합니다.

Payload 사양(운영자 요약)

모든 Webhook 메시지는 JSON 본문과 API 키 헤더를 포함한 HTTP POST를 사용합니다.

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

Envelope(버전 관리):
{
"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 (예: cameraDisconnectEvent)",
"errorCode": 1001,
"description": "string"
}
}

응답 코드:

성공: HTTP 200 OK 또는 204 No Content
일반적인 오류: 400(잘못된 페이로드), 401(잘못된 API 키), 403, 500

재시도: 현재 버전은 한 번만 전송하며 자동 재시도를 수행하지 않습니다. 복원력이 높은 ServiceNow 엔드포인트를 설계하는 것이 좋습니다.

지원되는 이벤트(specVersion 1.0)

카메라 연결 끊김 → cameraDisconnectEvent
카메라 IP 충돌 → cameraIpConflictEvent
라이선스 문제 → licenseIssueEvent
네트워크 문제 → networkIssueEvent
서버 인증서 오류 → serverCertificateError
서버 충돌 → serverConflictEvent
서버 장애 → serverFailureEvent
서버 시작됨 → serverStartEvent(현재 비활성화됨)
스토리지 문제 → storageFailureEvent
장치 연결 끊김(PoE 스위치) → deviceDisconnectEvent
이미지 상태 문제 → imageHealthIssueEvent

UI 일치

HealthPro UI에서 사용 가능하거나 표시되는 이벤트 옵션은 작업 생성 옵션을 따릅니다. 작업에서 지원되지 않는 유형은 Webhook 선택 항목에서 제외합니다.

감사 추적(사용자 로그)

범주: Webhook
자동(활성화됨): 세부 정보 “On: Enabled webhooks - Events & tasks.”
취소됨(비활성화됨): 세부 정보 “Off: Disabled webhooks - Events & tasks.”
사용자 로그 CSV 내보내기에 새 범주/세부 정보가 포함되며, 사용자 로그에서 Webhook 필터를 사용할 수 있습니다.

보안 모범 사례

모든 요청에서 X-HP-API-KEY를 검증하고 일반 텍스트로 기록하지 않습니다.
HTTPS만 제공하고 ServiceNow 측에서 IP 허용 목록 및 속도 제한을 적용하는 것을 고려합니다.
중복을 방지하기 위해 멱등성에 eventId를 사용합니다.

요약