---
title: 웹훅
description: 여정 상태가 변경될 때 IDCloud가 시스템에 알리는 위치, API에 대한 인증 방식, API가 응답하지 않을 때 발생하는 일을 설정합니다.
canonical: https://developer.unico.io/ko/dual-api/product-guide/portal-idcloud/settings/webhook
locale: ko
generated_by: markdown-export
---

**웹훅**은 신원 확인 여정에서 어떤 일이 발생했을 때 IDCloud가 시스템에 자동으로 알리는 방식입니다. 시스템이 "벌써 끝났나요?"라고 계속 확인하는
대신, IDCloud는 이벤트가 발생하는 즉시 API를 호출합니다.

이 화면에서는 API 주소, IDCloud가 그 주소에 인증하는 방식, 그리고 응답이 없을 때 발생하는 일을 설정합니다.

:::info
**대상:** 폴링 없이 여정 결과를 자동으로 받고자 하는 고객입니다. 모든 통합 유형에 적용됩니다.

**시스템에서 달라지는 점:** IDCloud를 폴링할 필요 없이, 상태가 변경될 때마다 알림을 받게 됩니다.

**찾는 위치:** IDCloud 포털 → 사이드바 **설정** → **웹훅** 탭.
:::

## 시작하기 전에

### 접근 권한

사용자에게는 **Configurator** 프로필이 필요합니다 — 여정 커스터마이징에 대한 접근 권한을 부여하는 것과 동일한 프로필입니다. 웹훅 탭이
표시되지 않으면 계정 관리자에게 문의하세요.

### 설정이 적용되는 방식

| | |
| :- | :- |
| **범위** | **테넌트와 브랜치**당 웹훅 하나입니다. 목록은 없습니다. 이미 설정된 웹훅이 있으면 새로 만들어지는 것이 아니라 수정됩니다. |
| **환경 분리** | 스테이징 포털은 UAT 웹훅을 설정하고, 프로덕션 포털은 프로덕션 웹훅을 설정합니다. 하나를 설정해도 다른 하나에는 영향을 주지 않습니다. |
| **적용 시점** | 저장하는 즉시 적용됩니다. |
| **시크릿 보안** | 시크릿은 암호화되며 평문으로 다시 표시되지 않습니다. 화면에서는 항상 마스킹되어 표시됩니다. |

### 미리 준비해야 할 것

- 알림을 받을 API의 **HTTPS URL**. 저장하기 전에 이미 운영 중이며 요청을 받을 수 있는 상태여야 합니다.
- 선택한 인증 방식에 따라 API가 요구하는 **자격 증명**(3단계 참조).
- API에 처리 한도가 있다면, 지원 가능한 **초당 요청 수**.

### 사전에 결정해야 할 것

두 가지 기술적인 결정은 포털을 운영하는 사람이 아니라 API를 관리하는 사람에게 달려 있습니다. 화면을 열기 전에 합의해 두는 것이 좋습니다.

- API가 요구하는 **인증 방식**.
- **재시도를 조정할지** 아니면 기본값을 유지할지. 기본값은 대부분의 경우에 적합합니다.

## 단계별 안내

### 1단계 — 웹훅 탭 열기

IDCloud 포털에서 사이드바의 **톱니바퀴 아이콘(설정)**을 클릭하고 **웹훅** 탭을 선택합니다.

아직 설정된 웹훅이 없으면 화면에 **"생성된 웹훅 없음"** 메시지와 **웹훅 생성** 버튼이 표시됩니다. 이미 웹훅이 있으면 엔드포인트, 인증 유형,
마스킹된 시크릿이 표시된 **내 웹훅** 카드와, 이를 수정할 수 있는 **웹훅 구성** 버튼이 표시됩니다.

![웹훅 구성 버튼이 있는 웹훅 관리 카드](/img/product-guide/webhook/en/01-manage-webhook.png)

*엔드포인트, 인증 유형, 마스킹된 시크릿이 표시된 "내 웹훅" 카드.*

### 2단계 — API URL 입력하기

**웹훅 생성**(이미 웹훅이 있다면 **웹훅 구성**)을 클릭하고, "클라이언트 정보" 아래의 **클라이언트 URL(엔드포인트)** 필드를 입력합니다.

이것은 IDCloud가 알림을 보낼 주소입니다. **HTTPS**여야 합니다.

**이미 운영 중인 주소를 입력하세요.** 저장하는 즉시 IDCloud는 이 URL을 호출하기 시작합니다. 아직 존재하지 않는 주소라면 첫 알림이 실패하고,
팀이 알아차리기도 전에 재시도 횟수를 모두 소진하게 됩니다.

![HTTPS 요구 사항에 대한 도움말 텍스트가 있는 엔드포인트 필드](/img/product-guide/webhook/en/02-edit-webhook.png)

*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를 관리하는 담당자와 인증 방식을 확인하세요.** 잘못된 인증 방식을 선택해도 화면에 오류가 표시되지 않습니다 — 이후 알림이
조용히 실패하게 되며, 결과가 도착하지 않을 때에야 비로소 문제를 알게 됩니다.

![인증 유형 필드와 그에 맞는 자격 증명 필드](/img/product-guide/webhook/en/02-edit-webhook.png)

*인증 유형 필드와 그에 대응하는 자격 증명 필드.*

### 4단계 — 필요하다면 재시도 조정하기

**재시도 설정** 섹션은 **선택 사항**이며 기본적으로 꺼져 있습니다. 기본 동작을 변경해야 할 때만 켜세요.

켜면 여섯 개의 필드가 나타납니다.

| 필드 | 제어하는 항목 | 기본값 |
| :- | :- | :- |
| **최대 재시도 횟수** | 포기하기 전까지 IDCloud가 다시 시도하는 횟수 | — |
| **속도 제한(req/s)** | 초당 최대 알림 수. API 처리 능력이 제한적이면 낮추세요 | — |
| **최소 시간(초)** | 시도 간 최소 간격 | 2초 |
| **최대 시간(초)** | 시도 간 최대 간격 | 10초 |
| **최대 지속 시간(초)** | 실패로 간주하기 전까지 한 번의 시도를 기다리는 시간 | 2초 |
| **최대 증가 횟수** | 시도 간 간격의 증가율(백오프) | 5 |

결합된 동작 방식은 다음과 같습니다. IDCloud는 시도하고, **최소 시간**만큼 기다린 뒤 다시 시도하며, **최대 증가 횟수**에 따라 간격을
늘려가면서 **최대 시간**까지 도달합니다 — 이 과정을 **최대 재시도 횟수**에 도달할 때까지 반복합니다. 각 개별 시도는 **최대 지속 시간**이
지나면 포기합니다.

**다른 항목을 만지기 전에 먼저 속도 제한을 조정하세요.** API가 부하로 다운된다면 문제는 처리량이지 재시도가 아닙니다 — 이런 상황에서
재시도를 늘리면 호출이 늘어나기 때문에 오히려 상황이 악화됩니다. 먼저 속도를 낮추세요.

**최대 재시도 횟수를 늘리는 것이 안정적인 API를 대신하지는 못합니다.** 재시도는 일시적인 장애 상황을 보완할 뿐입니다. API가 자주
실패한다면, 이 설정은 알림을 놓치는 시점을 늦출 뿐입니다.

![토글을 켠 후 표시되는 여섯 개의 재시도 필드](/img/product-guide/webhook/en/02-edit-webhook.png)

*토글을 켠 후 표시되는 여섯 개의 재시도 필드.*

### 5단계 — 저장하기

**저장**을 클릭합니다. **취소**를 클릭하면 모든 변경 내용이 취소되고 이전 설정이 유지됩니다.

인증 방식이 OAuth 2.0인 경우, IDCloud는 저장을 허용하기 전에 토큰 URL을 검증합니다.

저장한 후 **내 웹훅** 카드에 엔드포인트와 인증 유형이 표시됩니다. 시크릿은 마스킹되어 표시되며 화면에서 더 이상 확인할 수 없습니다 — 값을
잃어버린 경우 새로 설정해야 합니다.

**완료로 간주하기 전에 실제 테스트를 실행하세요.** 스테이징에서 여정을 시작하고 알림이 API에 도착했는지 확인하세요. 이 화면은 설정이
저장되었음을 확인해줄 뿐, API가 알림을 수신했음을 확인해주지는 않습니다.

## 자주 묻는 질문

**웹훅을 두 개 이상 등록할 수 있나요?** 아니요. 테넌트와 브랜치당 웹훅은 하나입니다. 이미 존재하는 경우 수정되며, 두 번째 웹훅을 만들
방법은 없습니다.

**스테이징에서 설정했습니다. 프로덕션에도 적용되나요?** 아니요. 두 환경은 독립적입니다. 스테이징 포털은 UAT 웹훅을 설정하고, 프로덕션
포털은 프로덕션 웹훅을 설정합니다. 프로덕션 포털에서도 동일한 설정을 다시 해야 합니다.

**등록한 시크릿을 어떻게 확인할 수 있나요?** 확인할 수 없습니다. 저장 시 암호화되며 항상 마스킹되어 표시됩니다. 값을 잃어버렸다면 시크릿
필드를 통해 새 값을 등록하세요 — 값을 입력하면 이전 값이 덮어써집니다.

**웹훅을 수정했지만 시크릿은 변경하고 싶지 않습니다. 어떻게 해야 하나요?** 시크릿 필드를 비워두세요. 현재 값이 그대로 유지됩니다.

**웹훅을 삭제하려면 어떻게 하나요?** 이 화면에서는 삭제 기능을 제공하지 않습니다. 설정을 제거하려면 Unico 지원팀에 문의하세요. 알림
수신을 중단하거나 대상만 변경하려는 것이라면, 대신 URL을 수정하세요.

**저장했는데 알림이 도착하지 않습니다.** 다음 순서로 확인하세요. URL이 올바르고 HTTPS인지, API가 운영 중인지, 인증 방식이 API가
기대하는 것과 일치하는지, 그리고 시크릿이 올바르게 입력되었는지. 인증 실패는 이 화면에서 오류로 표시되지 않습니다 — 전달 시점에 발생합니다.

**"최대 지속 시간"과 "최대 시간"의 차이는 무엇인가요?** "최대 시간"은 두 번의 시도 **사이**의 가장 긴 간격입니다. "최대 지속 시간"은
IDCloud가 실패로 간주하기 전까지 **한 번의** 시도를 기다리는 시간입니다.

**이미 API로 결과를 폴링하고 있다면 웹훅이 필요한가요?** 필수는 아니지만, 시스템이 폴링할 필요가 없어집니다. 이미 작동하는 폴링 루틴이
있다면, 웹훅은 필수 요건이 아니라 최적화 수단입니다.

## 빠른 참조

```text
IDCloud 포털
 └─ 설정(사이드바의 톱니바퀴 아이콘)
     └─ 웹훅 탭
         ├─ 클라이언트 정보 ....... 클라이언트 URL(엔드포인트), HTTPS
         ├─ 인증 ................. 없음 | API Key | Basic Auth | OAuth 2.0
         │                       OAuth 2.0: + 인증 URL 및 Client ID
         └─ 재시도(선택 사항) ..... 최대 재시도 횟수
                                   속도 제한(req/s)
                                   최소 시간(2초) · 최대 시간(10초)
                                   최대 지속 시간(2초) · 최대 증가 횟수(5)

테넌트와 브랜치당 웹훅 1개 · UAT와 프로덕션 독립적 · 시크릿 절대 표시 안 됨 · 취소 · 저장
```