> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 연동 정보
> API 키, 웹훅 설정, 리턴 URL, 결과 페이지 스킵, 동적 필드 등 시스템 연동을 위한 설정 방법을 안내합니다.
연동 정보 설정은 고객사의 시스템과 실시간 데이터 연동을 지원하는 기능입니다. API 키 관리, 웹훅 설정, 리턴 URL 구성, 동적 필드 설정 등을 통해 비즈니스 시스템과의 원활한 연동을 구축할 수 있습니다.
***
## API 키
해당 프로젝트의 API 키를 확인하고 관리할 수 있습니다.
API 키는 ARGOS ID Check API를 호출할 때 인증에 사용되는 고유 키입니다. 모든 API 요청에 `x-api-key` 헤더에 포함하여 전송해야 합니다.
**API 키 보안**
API 키는 외부에 노출되지 않도록 주의하세요. API 키가 유출되면 프로젝트의 모든 데이터에 접근할 수 있으므로, 안전하게 관리해야 합니다.
**API 키 활용**
API 키를 사용하여 제출건 조회, 승인/거절 처리, 토큰 관리 등 다양한 API 기능을 사용할 수 있습니다.
***
## 웹훅 설정
웹훅(Webhook) 기능은 고객사의 시스템과 실시간 데이터 연동을 지원하는 기능입니다. 특정 이벤트 발생 시 고객사에서 설정한 엔드포인트(Endpoint URL)로 HTTP POST 요청을 전송하여 별도의 API 호출 없이 실시간 알림을 수신하고 데이터를 처리할 수 있도록 지원합니다.
### 웹훅 URL 설정
고객사 시스템에서 웹훅 데이터를 수신할 엔드포인트 URL을 설정합니다.
웹훅 이벤트 발생 시 설정된 URL로 HTTP POST 요청이 전송됩니다.
**웹훅 보안 및 안정성**
웹훅 엔드포인트는 HTTPS를 사용하여 안전한 데이터 전송을 보장해야 합니다. 또한 웹훅 요청의 진위성을 확인하기 위한 서명 검증 메커니즘을 구현하는 것을 권장합니다.
**방화벽 설정 필수**
아르고스에서 웹훅을 보낼 때 사용하는 IP 주소는 **52.78.194.237**입니다. 웹훅을 정상적으로 수신하려면 방화벽 설정을 통해 이 IP 주소에서 오는 요청을 허용하도록 조치해야 합니다.
**방화벽 설정 방법**
고객사의 방화벽 또는 보안 그룹 설정에서 다음 IP 주소를 허용 목록에 추가하세요:
* **웹훅 IP**: `52.78.194.237`
이 IP 주소에서 오는 HTTP POST 요청을 허용하지 않으면 웹훅이 차단되어 수신할 수 없습니다.
**웹훅 IP 및 URL 관리**
해당 페이지에서만 각 프로젝트별로 고정된 웹훅 IP를 확인할 수 있으며, 웹훅 URL 변경 이력은 저장되지 않고 있으므로 해당 웹훅 URL 관리에 유념해주시기 바랍니다.
### 알림 사용자 관리
알림 사용자 관리를 통해 이름과 이메일을 추가하면, 다음날 아침에 어제 발송한 웹훅들에 대한 정보를 이메일로 받을 수 있습니다.
**설정 방법:**
1. 이름과 이메일 주소를 입력합니다.
2. 추가 버튼을 클릭하여 알림 사용자를 등록합니다.
3. 등록된 사용자는 매일 아침 전날 발송된 웹훅 정보를 이메일로 수신합니다.
**일일 웹훅 리포트**
등록된 알림 사용자에게는 매일 아침 전날(00:00 \~ 23:59 UTC)에 발송된 모든 웹훅 이벤트에 대한 요약 정보가 이메일로 전송됩니다. 이를 통해 웹훅 전송 현황을 모니터링할 수 있습니다.
***
## 리턴 URL
사용자가 KYC를 완료하거나 **오류 페이지로 이동한 경우**에도 설정한 URL로 리디렉션됩니다.
KYC 프로세스가 완료되고 제출자가 "Ok" 버튼을 선택하거나 5초간 대기하면, 동적 필드에서 선택한 파라미터와 함께 리턴 URL로 리디렉션됩니다. 2026-04 업데이트부터는 **오류 페이지 진입 후에도** 리턴 URL 로 이동할 수 있으며, 이때는 `errorCode` 파라미터가 함께 전달되어 고객사가 차단 사유를 식별할 수 있습니다.
**리턴 URL 예시 (정상 완료):**
```
https://yourapp.com/verification-complete?userid=user123&email=user@example.com&kycStatus=approved&submissionId=sub_abc123&cf1=campaign_summer
```
**리턴 URL 예시 (오류 페이지 → 리턴 URL):**
```
https://yourapp.com/verification-complete?kycStatus=rejected&errorCode=DE-20000
```
### 리턴 URL 암호화
리턴 URL 암호화 기능을 활성화하면, 리턴 URL의 파라미터가 암호화되어 전달됩니다.
리턴 URL 암호화를 활성화하면, 동적 필드에서 선택한 파라미터들이 `encrypted` 파라미터에 암호화되어 포함됩니다.
**암호화된 리턴 URL 예시:**
```
https://yourapp.com/verification-complete?encrypted={암호화된_데이터}
```
**리턴 URL 암호화 활용**
민감한 정보(이메일, 사용자 ID 등)를 포함한 리턴 URL을 사용하는 경우, 암호화 기능을 활성화하여 보안을 강화할 수 있습니다. 복호화 시 AES-256-ECB 방식을 사용합니다.
리턴 URL 암호화 데이터 복호화 방법을 확인하세요.
**리턴 URL 활용**
KYC 완료 후 사용자를 고객사의 서비스 페이지로 자동 리디렉션하여, 승인/거절 상태에 따라 맞춤형 안내 페이지를 제공할 수 있습니다.
***
## 결과 페이지 스킵
KYC 결과를 사용자가 보는 것을 스킵하고 본인이 원하는 URL로 리디렉션할 수 있습니다.
결과 페이지 스킵 기능을 활성화하면, KYC 결과 페이지를 건너뛰고 바로 리턴 URL로 이동합니다.
**활용 시나리오:**
* 고객사에서 자체 결과 페이지를 제공하고 싶을 때
* 결과에 대한 부분을 리턴 URL의 동적 필드 파라미터를 통해 유연하게 제공하고 싶을 때
**결과 페이지 스킵과 동적 필드 조합**
결과 페이지 스킵 기능을 활성화하고 동적 필드에서 `kycStatus`, `submissionId` 등의 파라미터를 선택하면, 리턴 URL에 KYC 결과 정보가 포함되어 전달됩니다. 이를 통해 고객사에서 자체 결과 페이지를 구성할 수 있습니다.
***
## 동적 필드
동적 필드의 체크박스를 클릭하여 리턴 URL 쿼리 파라미터로 전달할 항목을 선택할 수 있습니다. 설정된 값은 화면 하단의 **최종 리턴 URL** 프리뷰에 자동으로 반영됩니다.
| 필드 | 파라미터 키 | 설명 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------------------------------- |
| **유저 ID** | `userid` | 사용자 ID |
| **이메일** | `email` | 사용자 이메일 주소 |
| **제출 ID** | `submissionId` | 제출 ID (Submission ID) |
| **커스텀 필드 #1·#2·#3** | `cf1`, `cf2`, `cf3` | 사용자 정의 필드 |
| **KYC 결과** | `kycStatus` | KYC 결과 상태 (`approved`, `pending`, `rejected`) |
| **에러 코드** 2026-04 신규 | `errorCode` | 오류 페이지 진입 시 함께 전달되는 에러 코드 (예: `DE-20000`, `TK-10001`) |
**최종 리턴 URL 프리뷰:**
```
https://argosidentity.com?kycStatus={kycStatus}&errorCode={errorCode}
```
**에러 코드(`errorCode`) 파라미터 활용**
`에러 코드`를 동적 필드에 체크하면, 사용자가 오류 페이지로 이동한 이후에도 리턴 URL 버튼을 통해 고객사 서비스로 복귀할 수 있습니다. 이때 URL 쿼리스트링에 `errorCode` 값이 포함되어, 고객사 측에서 차단 사유(예: Device Verification 실패, 토큰 만료)를 식별할 수 있습니다. 전체 에러 코드 매핑은 [에러 코드와 에러 페이지](/ko/idcheck/reference_tables/Error-codes-and-pages) 문서를 참고하세요.
**동적 필드 주의사항**
`kycStatus`, `errorCode` 파라미터는 camelCase를 따르므로 대소문자를 정확히 구분해야 합니다. `kycStatus`는 결과에 따라 `approved`, `pending`, `rejected` 중 하나의 값이 리턴됩니다.
***
## 웹훅 이벤트 종류
웹훅을 통해 전송되는 주요 이벤트 종류는 다음과 같습니다:
| 이벤트 | 설명 |
| --------------- | ------------------------- |
| **approved** | KYC 인증이 승인되었을 때 발생 |
| **rejected** | KYC 인증이 거절되었을 때 발생 |
| **pending** | 수동 검수가 필요한 상태로 변경되었을 때 발생 |
| **retry** | 재시도가 발생했을 때 발생 |
| **updated** | 제출건 정보가 업데이트되었을 때 발생 |
| **delete** | 제출건이 삭제되었을 때 발생 |
| **submit** | 새로운 제출이 완료되었을 때 발생 |
| **token** | 토큰 관련 이벤트 발생 시 |
| **injection** | 데이터 주입 시 발생 |
| **aml** | AML 검사 결과 발생 시 |
| **aml-ongoing** | AML 온고잉 모니터링 결과 발생 시 |
***
## 활용 사례
금융기관에서 신규 고객의 KYC 인증이 완료되면 웹훅을 통해 즉시 알림을 받아 계좌 개설, 카드 발급, 서비스 활성화 등의 후속 프로세스를 자동으로 진행할 수 있습니다. 리턴 URL과 동적 필드를 활용하여 승인/거절 상태에 따라 고객에게 맞춤형 안내 페이지를 제공할 수 있습니다.
KYC 제출이 거절되거나 특정 위험 요소가 감지되었을 때 웹훅을 통해 운영팀에게 즉시 알림을 전송하여 빠른 대응이 가능합니다. 알림 사용자 관리 기능을 통해 매일 아침 전날 웹훅 전송 현황을 확인할 수 있습니다.
결과 페이지 스킵 기능과 동적 필드를 활용하여 고객사에서 자체 결과 페이지를 구성할 수 있습니다. 리턴 URL에 KYC 결과 정보를 포함하여 전달하므로, 별도의 API 호출 없이도 즉시 결과를 처리할 수 있습니다.
***
## 관련 문서
프로젝트 기본 정보 설정을 확인합니다.
웹훅 이벤트의 전체 개요를 확인합니다.
리턴 URL 사용 방법을 자세히 확인합니다.
승인 웹훅 페이로드를 확인합니다.
거절 웹훅 페이로드를 확인합니다.
API 사용 방법을 확인합니다.