---
title: 설정
description: IDCloud 웹훅 구성 단계별 가이드 — 웹 및 SDK를 위한 포털 셀프서비스와 Check 오케스트레이션을 사용하는 API 통합을 위한 클라이언트별 구성(브라질 전용).
canonical: https://developer.unico.io/ko/dual-api/developers/webhooks-and-events/setup
locale: ko
generated_by: markdown-export
---

IDCloud는 통합 방식에 따라 두 가지 웹훅 모달리티를 지원합니다:

- **포털 방식** — 웹 및 SDK 통합용. IDCloud 포털에서 직접 셀프서비스로 구성합니다.
- **클라이언트별 방식** — **Check 오케스트레이션** 기능(비동기 플로우)을 사용하는 API 통합용. Unico 팀에서 구성합니다. **브라질 전용**으로 제공됩니다.

### 포털 방식 (Web & SDK)

웹훅 엔드포인트를 등록하거나 업데이트하려면 IDCloud 포털에 접속하여 **설정 > 웹훅**으로 이동하세요.

#### 필수 정보

| 필드 | 설명 |
|---|---|
| **알림 URL** | Unico가 이벤트 알림을 전달하기 위해 호출할 엔드포인트. HTTPS로 접근 가능해야 합니다. |
| **인증 유형** | Unico가 엔드포인트에 인증하는 방법. 아래 옵션을 참조하세요. |
| **재시도 설정** | 최대 시도 횟수 및 시도 간격(지수 백오프 적용). |
| **동시성 제한** | 최대 동시 처리 중인 전달 수(최대: **500**). |
| **타임아웃** | 엔드포인트 응답의 최대 대기 시간(초). |
| **알림할 상태** | 알림을 트리거하는 프로세스 상태 집합. 현재 `PROCESS_STATE_FINISHED`로 고정되어 있으며, 현재는 구성할 수 없습니다. |

#### 인증 방법

****OAuth2****

제공 사항:

  - 웹훅 `endpoint`
  - OAuth2 공급자 `URL`
  - OAuth2 공급자 `ClientId`
  - OAuth2 공급자 `Secret`

  Unico는 클라이언트 자격 증명을 사용하여 공급자 URL에서 액세스 토큰을 요청하고 Bearer 토큰으로 엔드포인트에 전달합니다.

****Basic Authorization****

`user:pass` 형식으로 자격 증명을 제공하세요. Unico는 이를 Base64로 인코딩하여 모든 웹훅 호출의 `Authorization: Basic <encoded>` 헤더로 전송합니다.

****API Key****

두 가지 형식이 지원됩니다. 문자열은 **첫 번째** 콜론을 기준으로 분리됩니다:

  - `header:value` — 사용자 지정 헤더 이름을 설정합니다. 예시:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value`만 (콜론 없음) — 값이 스킴 접두사 없이 `Authorization` 헤더로 전송됩니다. 예시: `abc123` → `Authorization: abc123`.

  Bearer 스킴이 필요한 경우 `header:value` 형식을 사용하세요 (예: `Authorization:Bearer <token>`); 값만 있는 형식은 접두사 없이 원시 값을 전송합니다.

****인증 없음****

자격 증명이 전송되지 않습니다. 개발 환경에서만 권장됩니다 — 프로덕션 엔드포인트는 항상 인증을 요구해야 합니다.

#### 알림을 트리거하는 프로세스 상태

현재 Unico는 프로세스가 다음 상태로 전환될 때마다 알림을 보냅니다:

| 상태 | 설명 |
|---|---|
| `PROCESS_STATE_FINISHED` | 프로세스 완료 — 결과에 관계없이 최종 상태. |

:::warning[상태는 변경될 수 있습니다]
플랫폼에서 알림하는 상태 집합은 향후 변경될 수 있습니다. 엔드포인트가 반응하는 상태를 **구성 가능**하게 만들어 새 상태를 추가할 때 서비스를 재배포하지 않아도 되도록 하세요.
:::

#### 요청 형식

웹훅 전달은 엔드포인트에 대한 **POST** 요청입니다. 본문에는 프로세스 식별자와 현재 상태가 포함됩니다.

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`lastEvent` 및 `lastEventDescription`]
이 두 필드는 사용자가 여정을 완료하기 전에 프로세스가 만료된 경우에만 페이로드에 나타납니다. 정상 완료 페이로드에서는 존재하지 않습니다. 전체 스키마와 가능한 `lastEvent` 값 목록은 [이벤트 유형](/developers/webhooks-and-events/event-types)을 참조하세요.
:::

#### 예상 응답

엔드포인트는 **동기적으로** 응답해야 합니다:

- **성공**: `200`–`299` 범위의 모든 HTTP 상태.
- **실패**: 다른 모든 상태. Unico는 구성된 최대 시도 횟수에 도달하거나 `2xx`를 받을 때까지 지수 백오프로 재시도합니다.

:::tip[빠르게 응답하세요]
구성된 타임아웃 이내에 웹훅을 빠르게 확인하고 페이로드를 자체적으로 비동기 처리하세요. 웹훅 핸들러 내에서 장시간 처리하면 타임아웃 및 불필요한 재시도가 발생할 가능성이 높아집니다.
:::

멱등성 및 재시도 처리 지침은 [보안](/developers/webhooks-and-events/security)을 참조하세요.

### 클라이언트별 방식 (API — 브라질 전용)

:::info[브라질 전용]
클라이언트별 웹훅은 **Check 오케스트레이션** 기능을 사용하는 브라질 내 API 통합에서만 사용 가능합니다 — 프로세스 결과가 동기 API 응답이 아닌 웹훅을 통해 전달되는 비동기 플로우입니다.
:::

엔드포인트를 등록하거나 업데이트하려면 **CS / 온보딩** 팀에 문의하세요.

#### 필수 정보

| 필드 | 설명 |
|---|---|
| **알림 URL** | 상태 업데이트를 수신하기 위해 시스템이 노출하는 엔드포인트. HTTPS로 접근 가능해야 합니다. |
| **인증 유형** | Unico가 엔드포인트에 인증하는 방법. 아래 옵션을 참조하세요. |
| **재시도 설정** | 최대 시도 횟수 및 시도 간격(지수 백오프 적용). |
| **동시성 제한** | 최대 동시 처리 중인 전달 수(최대: **500**). |
| **타임아웃** | 엔드포인트 응답의 최대 대기 시간(초). |

#### 인증 방법

****OAuth2****

제공 사항:

  - 웹훅 `endpoint`
  - OAuth2 공급자 `URL`
  - OAuth2 공급자 `ClientId`
  - OAuth2 공급자 `Secret`

  Unico는 클라이언트 자격 증명을 사용하여 공급자 URL에서 액세스 토큰을 요청하고 Bearer 토큰으로 엔드포인트에 전달합니다.

****Basic Authorization****

`user:pass` 형식으로 자격 증명을 제공하세요. Unico는 이를 Base64로 인코딩하여 모든 웹훅 호출의 `Authorization: Basic <encoded>` 헤더로 전송합니다.

****API Key****

두 가지 형식이 지원됩니다. 문자열은 **첫 번째** 콜론을 기준으로 분리됩니다:

  - `header:value` — 사용자 지정 헤더 이름을 설정합니다. 예시:
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value`만 (콜론 없음) — 값이 스킴 접두사 없이 `Authorization` 헤더로 전송됩니다. 예시: `abc123` → `Authorization: abc123`.

  Bearer 스킴이 필요한 경우 `header:value` 형식을 사용하세요 (예: `Authorization:Bearer <token>`); 값만 있는 형식은 접두사 없이 원시 값을 전송합니다.

****인증 없음****

자격 증명이 전송되지 않습니다. 개발 환경에서만 권장됩니다 — 프로덕션 엔드포인트는 항상 인증을 요구해야 합니다.

#### 상태 코드

클라이언트별 웹훅은 **숫자 상태 코드**를 사용합니다:

| 코드 | 설명 |
|---|---|
| `2` | 불일치 — 신원 확인에서 불일치가 발생하며 프로세스가 완료됨. |
| `3` | 완료 — 프로세스가 성공적으로 완료됨. |
| `5` | 오류 — 프로세스가 오류로 종료됨. |

#### 요청 형식

웹훅 전달은 엔드포인트에 대한 **POST** 요청입니다. 본문에는 트랜잭션 식별자와 숫자 상태 코드가 포함됩니다.

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### 예상 응답

엔드포인트는 **동기적으로** 응답해야 합니다:

- **성공**: `200`–`299` 범위의 모든 HTTP 상태.
- **실패**: 다른 모든 상태. Unico는 구성된 최대 시도 횟수에 도달하거나 `2xx`를 받을 때까지 지수 백오프로 재시도합니다.

:::tip[빠르게 응답하세요]
구성된 타임아웃 이내에 웹훅을 빠르게 확인하고 페이로드를 자체적으로 비동기 처리하세요. 웹훅 핸들러 내에서 장시간 처리하면 타임아웃 및 불필요한 재시도가 발생할 가능성이 높아집니다.
:::

:::warning[최소 1회 이상 전달]
플랫폼은 최소 1회 이상 전달을 보장합니다 — 동일한 알림이 두 번 이상 도착할 수 있습니다. 중복을 안전하게 처리하기 위해 `id` 필드를 사용하여 멱등성을 구현하세요.

멱등성 및 재시도 처리 지침은 [보안](/developers/webhooks-and-events/security)을 참조하세요.
:::