웹훅 및 이벤트

Markdown

웹훅은 시스템 간 비동기 통합을 가능하게 하는 시스템 알림 서비스입니다 — Unico IDCloud는 프로세스 상태가 변경될 때마다 백엔드에 알림을 보내므로 업데이트를 폴링할 필요가 없습니다.

이 섹션에서는 웹훅 통합에 필요한 네 가지 항목을 다룹니다: 엔드포인트와 인증 설정 방법, Unico가 보내는 이벤트, 폴백 전략, 그리고 엔드포인트가 구현해야 하는 보안 및 안정성 패턴.

웹훅을 사용하는 경우

웹훅은 프로세스 완료 알림을 받는 권장 방법입니다. 특히 다음과 같은 경우에 유용합니다:

• Human Token Journey (humantoken, humantoken+revalidation) — 프로세스 생성로 생성한 프로세스의 여정을 사용자가 완료했을 때 알림을 받기 위해 사용합니다. 웹훅은 최종 상태(PROCESS_STATE_FINISHED)에서만 발생하며, 중간 진행 이벤트는 전달되지 않습니다.
• API Only 흐름 (api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation) — 결과가 이미 프로세스 생성 응답에 포함되므로, 이 흐름은 웹훅에 의존하지 않습니다.

웹훅은 GetProcess 엔드포인트를 보완하지만 대체하지는 않습니다. 폴백을 참조하세요.

이 섹션에서

• 설정 — 엔드포인트 등록, 인증 방법(OAuth2, Basic, API Key), 재시도 설정.
• 이벤트 유형 — Unico가 보내는 이벤트와 페이로드 구조.
• 보안 — 멱등성, 동시 처리 제한, 오류율.
• 폴백 — 웹훅을 사용할 수 없을 때 프로세스 결과를 조회하는 방법.