적용 대상: HealthPro

요약

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

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

중요: 웹후크를 구성할 수 있는 권한은 관리자 이상 역할만 가능합니다.

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

웹후크(Webhooks)

웹후크가 활성화 되면: 

• HealthPro는 선택된 이벤트에 대한 작업(알림 센터, 작업 로그)을 생성을 중단하고, 대신 해당 이벤트를 실시간으로 ServiceNow로 전송합니다.
   
• 웹후크 활성화 전에 생성된 기존 작업은 그래도 유지되며 조치가 가능합니다.
   
• 상태 로그는 계속해서 HealthPro에 기록됩니다.
   
• 알림 센터 UI 알림: “장치 이벤트를 타사 시스템으로 전송하도록 설정되어 작업 생성 및 로그 기록이 비활성화되었습니다.”

웹후크 연결하기

웹후크를 활성화하고 연결하려면:

1. 클라우드 포털에 로그인한 후 HealthPro를 클릭합니다.
    
2. 설정 > 타사 통합 > 웹후크로 이동합니다.
   
   
    
3. 웹후크를 켬으로 전환합니다.
    
4. 인증 방식: API Key(고정)를 선택합니다.
    
5. 인증 키 값: 키를 복사하여 붙여넣습니다.
    
6. 대상 URL: ServiceNow HTTPS 엔드포인트를 사용합니다. 
   
   예: https://dev-12345.service-now.com/api/...
    

7. 전송할 이벤트 유형을 선택합니다(기본값은 모두 선택됨; 지원되는 이벤트 참조). 

   키와 URL이 유효하고 대상이 허용 목록에 있으면 성공 메시지가 나타납니다.
   
   유효하지 않거나 허용 목록에 없으면 적용 실패하며 입력 값은 화면에 유지됩니다.

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

이벤트 발생량 조절(중복 억제 및 지연)

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

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

• 기본값: 활성화됨.
• 규칙: 같은 장치에서 타사로 이벤트(유형 무관)를 전송한 지 48시간 미만인 경우, 동일 장치에 대한 새 이벤트는 전송되지 않습니다.
• 툴팁: “같은 장치에서 타사로 이벤트를 전송한 지 48시간 미만인 경우, 동일 장치로 이벤트가 전송되지 않습니다.”
• 비활성화 시: 이벤트가 즉시 반복적으로 전송될 수 있습니다(이전 48시간 억제는 계속 적용됨).

2. 지연된 이벤트를 전송합니다.

• 기본값: 활성화됨.
• 규칙: 장치 오프라인/고장과 유사한 이벤트의 경우, HealthPro가 24시간 후 장치 상태를 재확인하며, 여전히 같은 상태인 경우에만 이벤트를 전송합니다. 이벤트 타임스탬프는 재확인 시간에 해당합니다.
  • 카메라 연결 끊김
  • 서버 고장
  • 장치 연결 끊김 (PoE 스위치)
  • 네트워크 문제
• 재확인 시 장치가 정상/온라인 상태라면 이벤트는 취소됩니다.
• 24시간 지연 기간 내에 동일한 네 가지 이벤트 유형의 추가 발생은 무시됩니다.
• 비활성화 시: 이벤트가 즉시 전송됩니다(기존에 진행 중인 지연 항목은 변경되지 않음).

ServiceNow에서 이벤트 확인하기

• 수신된 웹후크 이벤트(아래 페이로드 사양 참조)를 ServiceNow의 인시던트/이벤트/알림 테이블에 매핑합니다.
   
• 중복 방지와 업데이트를 위해 eventId를 사용합니다.
   
• CI/위치 관계를 위해 조직/위치/지역/게이트웨이 필드를 사용합니다.
   
• 반복 이벤트 시 새 레코드 생성 대신 기존 레코드를 업데이트합니다.
  
  

페이로드 사양 (운영자 요약)

모든 웹후크 메시지는 HTTP POST와 JSON 본문 및 API 키 헤더를 사용합니다.

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

인벨로프(버전 관리):
{
 "specVersion": "1.0",
 "eventId": "uuid",
 "eventType": "string",
 "occurredAt": "ISO-8601 타임스탬프",
 "source": "healthpro",
 "data": {
   "organizationId": "uuid",
   "locationId": "uuid",
   "locationName": "string",
   "areaId": "uuid (선택 사항)",
   "areaName": "string (선택 사항)",
   "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"
 }
}

응답 코드

• Success: HTTP 200 OK 또는 204 No Content
• Typical error: 400 (잘못된 페이로드), 401 (잘못된 API 키), 403, 500

Retry : 현재 버전은 1회 전송(자동 재시도 없음). 복원력이 뛰어난 ServiceNow 엔드포인트 설계를 고려하세요.

지원되는 이벤트 (specVersion 1.0)

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

UI 일관성

HealthPro UI에서 사용 가능/표시되는 이벤트 옵션은 작업 생성 옵션을 따릅니다. 작업에 지원되지 않는 유형은 웹후크 선택에서 제외하세요.

감사 추적 (사용자 로그)

• 카테고리: 웹후크
   
• 자동(활성화됨): 세부사항 “켜짐: 웹후크 활성화 - 이벤트 및 작업.”
   
• 취소됨(비활성화됨): 세부사항 “꺼짐: 웹후크 비활성화 - 이벤트 및 작업.”
   
• 사용자 로그 CSV 내보내기에 새 카테고리/세부사항 포함; 사용자 로그에 웹후크 필터 제공.

보안 모범 사례

• 모든 요청에서 X-HP-API-KEY를 검증하고 평문으로 로그하지 마세요.
   
• HTTPS만 제공하며, ServiceNow 측에서 IP 허용 목록 및 속도 제한을 고려하세요.
   
• 중복 방지를 위해 eventId를 사용하세요.

문제 해결

• 적용 실패: 대상 URL이 허용 목록 도메인 내의 HTTPS 엔드포인트인지, API 키가 올바른지 확인하세요.
   
• ServiceNow에 인시던트가 생성되지 않음: API 키 검증, 엔드포인트 경로, 웹후크가 켜져 있고 올바른 이벤트가 선택되었는지 확인하세요. 48시간 중복 억제 또는 24시간 지연이 활성화되어 있는지 점검하세요.
   
• HealthPro 작업에 아무것도 표시되지 않음: 웹후크가 켜져 있으면 정상입니다; 알림 센터 배너를 확인하세요.