---
title: 웹훅
description: '비대면 카드 검증 웹훅 알림을 설정하고 수신하는 방법: 요청/응답 형식과 요청 제한, 멱등성 같은 중요 고려 사항.'
canonical: https://developer.unico.io/ko/dual-api/developers/regional-solutions/card-not-present-verification/integration/webhook
locale: ko
generated_by: markdown-export
---

이 문서의 GetProcess 관련 문서들은 엔드포인트를 호출하여 프로세스의 상태를 가져오는 방법을 설명합니다. 이 방식은 생성된 프로세스에 대한 정보를 받기 위해 폴링을 수행하는 것입니다. 즉, 동일한 프로세스에 대해 최신 상태를 가져오기 위해 엔드포인트를 여러 번 호출할 수 있습니다.

웹훅을 사용하면 프로세스의 상태가 변경될 때마다 특정 엔드포인트에 알릴 수 있습니다.

### 웹훅이란 무엇인가요?

웹훅은 시스템 간의 비동기 통합을 가능하게 하는 시스템 알림 서비스로, 한 시스템이 트리거를 통해 다른 시스템에 알립니다. 이를 통해 웹훅은 업데이트를 확인하기 위한 지속적인 폴링 없이도 시스템을 최신 정보로 유지할 수 있습니다.

### 웹훅 설정 방법

웹훅을 설정하려면 다음 정보가 필요합니다:

- **알림 URL:** Unico가 상태 업데이트에 대한 알림을 보내는 데 사용하는 엔드포인트입니다.
- **인증 유형:** 엔드포인트 호출을 인증하는 데 사용되는 방식입니다. 다음 옵션을 사용할 수 있습니다:
  - OAuth2;
  - Basic Authorization;
  - API Key;
  - 인증 없음.
- **OAuth2**의 경우, 다음 정보를 제공해야 합니다:
  - 웹훅 `endpoint`;
  - OAuth2 제공자 `URL`;
  - OAuth2 제공자 `ClientId`;
  - OAuth2 제공자 `Secret`.
- Basic Authorization의 경우, `user:pass` 형식으로 전송해야 합니다.
- API Key의 경우, 두 가지 형식이 가능합니다:
  - 특정 헤더 이름을 지정하고자 할 때는 `header:value`;
  - 원하는 헤더가 `Authorization`일 때는 `value`.
- **재시도 설정:** 엔드포인트 호출이 실패할 경우의 시도 횟수를 나타냅니다:
  - 최대 시도 횟수;
  - 시도 간격(초 단위);
  - **요청 제한(Rate Limit):** 동시 전송 가능한 최대 횟수(최대: 500);
  - **타임아웃:** 엔드포인트 응답을 기다리는 최대 시간(초 단위).
- **알림받을 상태:** 알림을 받고 싶은 특정 상태를 구독할 수 있습니다. 다음이 포함됩니다:
  - `approved`: 거래 승인됨;
  - `processing`: 거래 처리 중;
  - `inconclusive`: 결정적인 검증을 수행할 수 없음;
  - `shared`: 거래가 공유되어 제출 대기 중;
  - `skipped`: 사용자가 흐름에서 생체 인식 캡처를 건너뜀;
  - `unknown-share`: 사용자가 구매를 인식하지 못한다고 표시함;
  - `absent-holder`: 카드 소유자가 캡처를 수행하기 위해 자리에 없음;
  - `expired`: 사용자가 지정된 시간 내에 캡처를 완료하지 못해 거래가 만료됨.

:::note[인증에 관하여]
API는 Basic Authentication 또는 API Key와 같은 인증 방식으로 보호될 수 있습니다. 추가적인 보호를 위해 접근이 허용된 유효한 IP 목록도 정의할 수 있습니다.
:::

### 비대면 카드 검증과의 통합

플랫폼에서 웹훅을 설정하면, 귀사가 이러한 업데이트를 수신하기 위해 개발한 API의 엔드포인트로 전송되는 알림을 통해 프로세스에 대한 정보를 받을 수 있습니다.

플랫폼이 API로 전송하는 정보는 다음을 포함합니다:

- **ID**: 거래 ID;
- **Status**: 거래 상태;
- **HasIdentityChanged**: 거래에서 신원 변경이 발생했는지 여부(선택 사항).

:::note
웹훅 설정을 통해 클라이언트가 알림받고 싶은 상태를 선택할 수 있다는 점에 유의하세요. 이 정보를 전송한 후, 예상되는 응답은 동기식이어야 합니다.
:::

#### 요청

요청은 정보를 더 쉽고 안전하게 전송할 수 있도록 REST API에 대한 POST 메서드여야 합니다. 모든 필드는 필수여야 합니다. 요청 본문은 다음 예시와 같이 거래 ID와 상태를 받아야 합니다:

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

#### 응답

응답은 동기식이어야 합니다. 성공한 요청의 상태는 200에서 299 사이여야 합니다. 그 외의 상태는 실패로 간주되며, 비대면 카드 검증은 2xx 응답을 받거나 최대 시도 횟수에 도달할 때까지 추가 알림 시도(시도 사이에 지수 백오프 적용)를 진행합니다.

#### 응답 상태

현재 저희는 일련의 상태들을 보유하고 있지만, 이 목록은 향후 변경될 수 있습니다. 따라서 클라이언트가 관심 있는 상태에 대해 조치를 취할 수 있도록 설정 가능하게 만드는 것이 권장됩니다. 예를 들어, 캡처가 성공적으로 완료될 때마다 조치를 취하려는 경우, 현재는 "processing" 상태에서 이 일이 발생합니다. 하지만 이는 향후 변경될 수 있으므로, 성공적인 캡처를 나타내는 상태를 시스템에서 설정 가능하게 만들어, 향후 "captured" 상태로 변경되더라도 쉽게 반영할 수 있도록 하는 것이 좋습니다.

또한, 특정 상태에 대한 구체적인 조치와 인식되지 않은 상태에 대한 일반적인 조치를 함께 마련하는 것을 권장합니다(예: "processing"과 "approved"가 아닌 모든 것을 결정 불가로 간주). 이는 향후 새로운 상태가 나타날 수 있으며, 이로 인해 웹훅이 중단되지 않아야 하기 때문에 중요합니다.

#### 중요 고려 사항

비대면 카드 검증이 상태 변경을 알리기 위해 사용할 API를 개발할 때는 다음 사항에 유의하세요:

**요청 제한(Rate limit)** — 거래가 많은 상황에서 리소스에 과부하가 걸리지 않도록, 엔드포인트가 호출될 수 있는 횟수에 상한선을 지정할 수 있습니다.

**오류율(Error Rate)** — 오류율([200, 299] 범위를 벗어난 응답)은 항상 낮게 유지되어야 합니다. 그렇지 않으면 웹훅 처리량이 자동으로 감소하며, 이 감소가 재시도 메커니즘과 결합되어 새로운 웹훅의 실행 시간이 늘어날 수 있습니다.

**멱등성(Idempotence)** — 현재 웹훅 구현은 최소 1회 전달(at-least-once delivery)을 보장하므로, 동일한 상태가 두 번 이상 알림될 수 있습니다. 따라서 엔드포인트 구현은 멱등성을 갖도록 이루어져야 합니다.

**폴백(Fallback)** — 웹훅 서비스가 이용 불가능한 경우를 대비하여, 설정된 응답 시간 내에 거래 상태를 계속 조회할 수 있도록 폴백 방법을 마련하는 것이 권장됩니다. 엔드포인트 조회는 이 문서의 [API 레퍼런스](/developers/regional-solutions/card-not-present-verification/integration/apis/api-reference) 섹션에 설명되어 있습니다.