웹훅
웹훅은 신원 확인 여정에서 어떤 일이 발생했을 때 IDCloud가 시스템에 자동으로 알리는 방식입니다. 시스템이 "벌써 끝났나요?"라고 계속 확인하는 대신, IDCloud는 이벤트가 발생하는 즉시 API를 호출합니다.
이 화면에서는 API 주소, IDCloud가 그 주소에 인증하는 방식, 그리고 응답이 없을 때 발생하는 일을 설정합니다.
대상: 폴링 없이 여정 결과를 자동으로 받고자 하는 고객입니다. byUnico와 byClient 통합 모두에 적용됩니다.
시스템에서 달라지는 점: IDCloud를 폴링할 필요 없이, 상태가 변경될 때마다 알림을 받게 됩니다.
찾는 위치: IDCloud 포털 → 사이드바 설정 → 웹훅 탭.
이 화면이 생기기 전에는 웹훅을 변경할 때마다 지원 티켓을 열어야 했습니다 — 그것만으로 한 달에 약 30건의 티켓이 발생했습니다. 이제는 스테이징과 프로덕션 모두에서 몇 분 만에 직접 처리할 수 있습니다.
시작하기 전에
접근 권한
사용자에게는 Configurator 프로필이 필요합니다 — 여정 커스터마이징에 대한 접근 권한을 부여하는 것과 동일한 프로필입니다. 웹훅 탭이 표시되지 않으면 계정 관리자에게 문의하세요.
설정이 적용되는 방식
| 범위 | 테넌트와 브랜치당 웹훅 하나입니다. 목록은 없습니다. 이미 설정된 웹훅이 있으면 새로 만들어지는 것이 아니라 수정됩니다. |
| 환경 분리 | 스테이징 포털은 UAT 웹훅을 설정하고, 프로덕션 포털은 프로덕션 웹훅을 설정합니다. 하나를 설정해도 다른 하나에는 영향을 주지 않습니다. |
| 적용 시점 | 저장하는 즉시 적용됩니다. |
| 시크릿 보안 | 시크릿은 암호화되며 평문으로 다시 표시되지 않습니다. 화면에서는 항상 마스킹되어 표시됩니다. |
미리 준비해야 할 것
- 알림을 받을 API의 HTTPS URL. 저장하기 전에 이미 운영 중이며 요청을 받을 수 있는 상태여야 합니다.
- 선택한 인증 방식에 따라 API가 요구하는 자격 증명(3단계 참조).
- API에 처리 한도가 있다면, 지원 가능한 초당 요청 수.
사전에 결정해야 할 것
두 가지 기술적인 결정은 포털을 운영하는 사람이 아니라 API를 관리하는 사람에게 달려 있습니다. 화면을 열기 전에 합의해 두는 것이 좋습니다.
- API가 요구하는 인증 방식.
- 재시도를 조정할지 아니면 기본값을 유지할지. 기본값은 대부분의 경우에 적합합니다.
단계별 안내
1단계 — 웹훅 탭 열기
IDCloud 포털에서 사이드바의 **톱니바퀴 아이콘(설정)**을 클릭하고 웹훅 탭을 선택합니다.
아직 설정된 웹훅이 없으면 화면에 "생성된 웹훅 없음" 메시지와 웹훅 생성 버튼이 표시됩니다. 이미 웹훅이 있으면 엔드포인트, 인증 유형, 마스킹된 시크릿이 표시된 내 웹훅 카드와, 이를 수정할 수 있는 웹훅 구성 버튼이 표시됩니다.
엔드포인트, 인증 유형, 마스킹된 시크릿이 표시된 "내 웹훅" 카드.
2단계 — API URL 입력하기
웹훅 생성(이미 웹훅이 있다면 웹훅 구성)을 클릭하고, "클라이언트 정보" 아래의 클라이언트 URL(엔드포인트) 필드를 입력합니다.
이것은 IDCloud가 알림을 보낼 주소입니다. HTTPS여야 합니다.
이미 운영 중인 주소를 입력하세요. 저장하는 즉시 IDCloud는 이 URL을 호출하기 시작합니다. 아직 존재하지 않는 주소라면 첫 알림이 실패하고, 팀이 알아차리기도 전에 재시도 횟수를 모두 소진하게 됩니다.
HTTPS 요구 사항에 대한 도움말 텍스트가 있는 엔드포인트 필드.
3단계 — IDCloud가 API에 인증하는 방식 선택하기
"인증" 아래에서 인증 유형을 선택합니다. 네 가지 옵션이 있으며, 각각 서로 다른 필드를 요구합니다.
| 유형 | 표시되는 필드 | 사용 시점 |
|---|---|---|
| 없음 | 없음 | API가 인증을 요구하지 않는 경우입니다. 다른 보호 수단이 있을 때만 사용하세요 — 인증이 없으면 URL을 알아낸 누구나 데이터를 보낼 수 있습니다 |
| API Key | 시크릿 | API가 고정된 키를 검증하는 경우입니다 |
| Basic Auth | 시크릿 | API가 HTTP Basic 방식으로 사용자 이름과 비밀번호를 사용하는 경우입니다 |
| OAuth 2.0 | 인증 URL, Client ID, 시크릿 | API가 토큰을 요구하는 경우입니다. IDCloud가 해당 URL에서 토큰을 가져와 자동으로 갱신합니다 |
OAuth 2.0의 경우 인증 URL은 IDCloud가 토큰을 가져오는 주소입니다 — 알림을 받는 URL이 아닙니다. 두 주소는 서로 다르며, 이를 혼동하는 것이 이 화면에서 가장 흔한 실수입니다.
시크릿은 암호화되어 저장됩니다. 기존 웹훅을 수정할 때 이 필드는 비어 있는 상태로 표시됩니다. 값을 입력하면 현재 시크릿을 덮어쓰고, 비워두면 기존 값이 그대로 유지됩니다.
저장하기 전에 API를 관리하는 담당자와 인증 방식을 확인하세요. 잘못된 인증 방식을 선택해도 화면에 오류가 표시되지 않습니다 — 이후 알림이 조용히 실패하게 되며, 결과가 도착하지 않을 때에야 비로소 문제를 알게 됩니다.
인증 유형 필드와 그에 대응하는 자격 증명 필드.
4단계 — 필요하다면 재시도 조정하기
재시도 설정 섹션은 선택 사항이며 기본적으로 꺼져 있습니다. 기본 동작을 변경해야 할 때만 켜세요.
켜면 여섯 개의 필드가 나타납니다.
| 필드 | 제어하는 항목 | 기본값 |
|---|---|---|
| 최대 재시도 횟수 | 포기하기 전까지 IDCloud가 다시 시도하는 횟수 | — |
| 속도 제한(req/s) | 초당 최대 알림 수. API 처리 능력이 제한적이면 낮추세요 | — |
| 최소 시간(초) | 시도 간 최소 간격 | 2초 |
| 최대 시간(초) | 시도 간 최대 간격 | 10초 |
| 최대 지속 시간(초) | 실패로 간주하기 전까지 한 번의 시도를 기다리는 시간 | 2초 |
| 최대 증가 횟수 | 시도 간 간격의 증가율(백오프) | 5 |
결합된 동작 방식은 다음과 같습니다. IDCloud는 시도하고, 최소 시간만큼 기다린 뒤 다시 시도하며, 최대 증가 횟수에 따라 간격을 늘려가면서 최대 시간까지 도달합니다 — 이 과정을 최대 재시도 횟수에 도달할 때까지 반복합니다. 각 개별 시도는 최대 지속 시간이 지나면 포기합니다.
다른 항목을 만지기 전에 먼저 속도 제한을 조정하세요. API가 부하로 다운된다면 문제는 처리량이지 재시도가 아닙니다 — 이런 상황에서 재시도를 늘리면 호출이 늘어나기 때문에 오히려 상황이 악화됩니다. 먼저 속도를 낮추세요.
최대 재시도 횟수를 늘리는 것이 안정적인 API를 대신하지는 못합니다. 재시도는 일시적인 장애 상황을 보완할 뿐입니다. API가 자주 실패한다면, 이 설정은 알림을 놓치는 시점을 늦출 뿐입니다.
토글을 켠 후 표시되는 여섯 개의 재시도 필드.
5단계 — 저장하기
저장을 클릭합니다. 취소를 클릭하면 모든 변경 내용이 취소되고 이전 설정이 유지됩니다.
인증 방식이 OAuth 2.0인 경우, IDCloud는 저장을 허용하기 전에 토큰 URL을 검증합니다.
저장한 후 내 웹훅 카드에 엔드포인트와 인증 유형이 표시됩니다. 시크릿은 마스킹되어 표시되며 화면에서 더 이상 확인할 수 없습니다 — 값을 잃어버린 경우 새로 설정해야 합니다.
완료로 간주하기 전에 실제 테스트를 실행하세요. 스테이징에서 여정을 시작하고 알림이 API에 도착했는지 확인하세요. 이 화면은 설정이 저장되었음을 확인해줄 뿐, API가 알림을 수신했음을 확인해주지는 않습니다.
자주 묻는 질문
웹훅을 두 개 이상 등록할 수 있나요? 아니요. 테넌트와 브랜치당 웹훅은 하나입니다. 이미 존재하는 경우 수정되며, 두 번째 웹훅을 만들 방법은 없습니다.
스테이징에서 설정했습니다. 프로덕션에도 적용되나요? 아니요. 두 환경은 독립적입니다. 스테이징 포털은 UAT 웹훅을 설정하고, 프로덕션 포털은 프로덕션 웹훅을 설정합니다. 프로덕션 포털에서도 동일한 설정을 다시 해야 합니다.
등록한 시크릿을 어떻게 확인할 수 있나요? 확인할 수 없습니다. 저장 시 암호화되며 항상 마스킹되어 표시됩니다. 값을 잃어버렸다면 시크릿 필드를 통해 새 값을 등록하세요 — 값을 입력하면 이전 값이 덮어써집니다.
웹훅을 수정했지만 시크릿은 변경하고 싶지 않습니다. 어떻게 해야 하나요? 시크릿 필드를 비워두세요. 현재 값이 그대로 유지됩니다.
웹훅을 삭제하려면 어떻게 하나요? 이 화면에서는 삭제 기능을 제공하지 않습니다. 설정을 제거하려면 Unico 지원팀에 문의하세요. 알림 수신을 중단하거나 대상만 변경하려는 것이라면, 대신 URL을 수정하세요.
저장했는데 알림이 도착하지 않습니다. 다음 순서로 확인하세요. URL이 올바르고 HTTPS인지, API가 운영 중인지, 인증 방식이 API가 기대하는 것과 일치하는지, 그리고 시크릿이 올바르게 입력되었는지. 인증 실패는 이 화면에서 오류로 표시되지 않습니다 — 전달 시점에 발생합니다.
"최대 지속 시간"과 "최대 시간"의 차이는 무엇인가요? "최대 시간"은 두 번의 시도 사이의 가장 긴 간격입니다. "최대 지속 시간"은 IDCloud가 실패로 간주하기 전까지 한 번의 시도를 기다리는 시간입니다.
이미 API로 결과를 폴링하고 있다면 웹훅이 필요한가요? 필수는 아니지만, 시스템이 폴링할 필요가 없어집니다. 이미 작동하는 폴링 루틴이 있다면, 웹훅은 필수 요건이 아니라 최적화 수단입니다.
빠른 참조
IDCloud 포털
└─ 설정(사이드바의 톱니바퀴 아이콘)
└─ 웹훅 탭
├─ 클라이언트 정보 ....... 클라이언트 URL(엔드 포인트), HTTPS
├─ 인증 ................. 없음 | API Key | Basic Auth | OAuth 2.0
│ OAuth 2.0: + 인증 URL 및 Client ID
└─ 재시도(선택 사항) ..... 최대 재시도 횟수
속도 제한(req/s)
최소 시간(2초) · 최대 시간(10초)
최대 지속 시간(2초) · 최대 증가 횟수(5)
테넌트와 브랜치당 웹훅 1개 · UAT와 프로덕션 독립적 · 시크릿 절대 표시 안 됨 · 취소 · 저장