> ## 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.

# Webhook

> ARGOS Identity가 고객사에게 검증 결과를 통보하는 Webhook 채널의 네트워크 통신 구조와 데이터 보안 정책.

## 1. 문서 개요

### 1.1 목적

Argos Identity가 고객사에게 검증 결과를 **Webhook(콜백) 방식**으로 통보하는 채널의 네트워크 통신 구조와 보안 정책을 정리한 자료입니다.

### 1.2 대상 독자

* 고객사의 정보보호·보안 검토 담당자
* Webhook 수신 엔드포인트를 구축·운영하는 개발팀
* 컴플라이언스 / 감사 부서

### 1.3 범위

* Argos → 고객사 방향의 Webhook 발송 통신
* 통신 프로토콜, TLS, 페이로드 암호화
* 인증·무결성·재시도·감사

***

## 2. 서비스 카테고리 소개

**Webhook**은 Argos가 KYC 처리 결과(승인 / 거부 / 재요청 등)를 고객사에게 **비동기 방식으로 통보**하는 채널입니다.

### 2.1 특징

* **이벤트 기반**: 결과 발생 시점에 즉시 발송 (폴링 불필요)
* **HTTPS 표준 준수**: 고객사가 별도 SDK 설치 없이 표준 HTTP 서버로 수신 가능
* **2단계 파이프라인 구조**:
  1. **이벤트 수렴 계층** (서버리스): 발송 대상 결정 + 본문 구성
  2. **발송 실행 계층** (전용 발송 서버): 고객사 엔드포인트로 HTTPS POST 실행

### 2.2 발송 트리거

| 이벤트      | 발송 시점                             |
| -------- | --------------------------------- |
| 검증 완료    | Liveform / Restful API에서 결과 확정 직후 |
| 검증 상태 변경 | 재검증 요청, 보완 요청 발생 시                |
| 관리자 작업   | 대시보드에서 수동 승인/거부 작업 발생 시           |

***

## 3. 네트워크 통신 흐름

### 3.1 전체 흐름

```mermaid theme={null}
flowchart TD
    K[KYC 검증 결과 확정] -->|AWS 호출<br/>SigV4| C["Webhook 이벤트 수렴 계층<br/>- 프로젝트 옵션 조회<br/>- 발송 본문 구성<br/>- 암호화 옵션 적용 옵션"]
    C -->|AWS 호출| S[Webhook 발송 실행 계층]
    S -->|HTTPS POST<br/>TLS 1.2+| E[고객사 Webhook 수신 엔드포인트]
    E -->|HTTP 200 OK / Non-2xx| L[발송 결과 감사 로그 적재]
```

### 3.2 외부 송신 채널

| 항목           | 값                                                    |
| ------------ | ---------------------------------------------------- |
| 방향           | Argos → 고객사 (Outbound from Argos)                    |
| 프로토콜         | HTTPS (TLS 1.2 이상 강제)                                |
| HTTP Method  | POST (고객 설정에 따라 변경 가능)                               |
| Content-Type | `application/json` (기본) / `text/plain` (암호화 옵션 활성 시) |
| 인증서 검증       | 고객사 측 인증서를 Argos가 검증 (rejectUnauthorized 활성)         |

***

## 4. 통신 프로토콜 및 규약

### 4.1 전송 계층

* **TLS 1.2 이상** (HTTPS Agent에서 명시적 강제: `secureProtocol: TLSv1_2_method`)
* 고객사 서버의 인증서는 표준 PKI 신뢰 체인(Root CA)으로 검증
* 자기서명(Self-signed) 인증서는 사전 협의 없이는 미지원

### 4.2 요청 헤더

| 헤더                    | 값 / 설명                                           |
| --------------------- | ------------------------------------------------ |
| `Content-Type`        | `application/json` (기본), `text/plain` (암호화 적용 시) |
| `User-Agent`          | Argos 자체 식별자 (예: `Argos-kyc-webhook`)            |
| `X-Webhook-Encrypted` | `true` / `false` — 본문 암호화 적용 여부 신호               |

### 4.3 요청 본문 (JSON, 평문 모드 기준)

```json theme={null}
{
  "projectId": "<프로젝트 식별자>",
  "submissionId": "<제출 식별자>",
  "userId": "<선택>",
  "status": "approved | rejected | incomplete",
  "timestamp": "<발송 시각>",
  "webhookParams": { ... }
}
```

본문 구조는 프로젝트 옵션 및 발송 이벤트 종류에 따라 일부 가변적이며, 상세 스펙은 별도 API 문서를 참고하십시오.

***

## 5. 데이터 암호화

### 5.1 전송 중 암호화 (필수)

* **TLS 1.2 이상 강제** (HTTPS only)
* 평문 HTTP 발송은 지원하지 않음

### 5.2 페이로드 암호화 (옵션, 프로젝트별 활성)

고객사가 추가 보안을 원할 경우, 본문에 대해 **TLS 위 추가 암호화**를 적용할 수 있습니다.

| 항목           | 값                                 |
| ------------ | --------------------------------- |
| 활성화 방법       | 프로젝트 옵션 `데이터 암호화` 활성              |
| 알고리즘         | AES-256 (대칭 키 암호화)                |
| 키 도출         | 프로젝트별 API Key 기반 키 도출             |
| 신호 헤더        | `X-Webhook-Encrypted: true`       |
| Content-Type | `text/plain` (Base64 인코딩된 암호문 전송) |

**복호화 절차 (고객사 측)**:

1. `X-Webhook-Encrypted` 헤더 확인
2. 본문(Base64 디코드 → 암호문) 획득
3. 프로젝트 API Key를 시드로 키 도출
4. AES-256 복호화 → JSON 파싱

***

## 6. 인증 및 인가

### 6.1 고객사 측 발송자 검증 옵션

| 방식                      | 설명                                                |
| ----------------------- | ------------------------------------------------- |
| **TLS 인증서 + 발송 도메인 검증** | 고객사가 Argos 발송 도메인의 인증서를 통해 출발지 검증                 |
| **IP 화이트리스트 (권장)**      | Argos 발송 서버의 고정 IP 범위만 수신 허용 (고객사 방화벽 설정)         |
| **암호화 모드 헤더**           | `X-Webhook-Encrypted: true` 검증 및 복호화 가능 여부로 출처 확인 |
| **고객사 등록 인증 헤더**        | 협의 시 Argos가 고객사 지정 인증 헤더(예: Bearer 토큰)를 함께 송신     |

<Tip>강력한 발송자 검증이 필요한 고객사는 **IP 화이트리스트 + 페이로드 암호화 모드** 의 조합 사용을 권장합니다.</Tip>

### 6.2 ARGOS 내부 인증

* 검증 계층 → Webhook 수렴 계층: AWS 내부 호출 (IAM Role + SigV4)
* Webhook 수렴 계층 → 발송 실행 계층:  AWS 네트워크 호출

***

## 7. 무결성 및 위·변조 방지

| 구간            | 무결성 보장 방식                     |
| ------------- | ----------------------------- |
| TLS 채널        | TLS 1.2+ 내장 무결성 (AEAD / HMAC) |
| 페이로드 (암호화 모드) | AES-256 + 복호화 성공 = 출처 검증      |
| TCP 전송        | TCP 체크섬 + TLS 종단 무결성          |
| 발송 로그         | 변경 불가(append-only) 감사 테이블 적재  |

***

## 8. 접근 통제 및 격리

### 8.1 발송 대상 격리

* 고객사 Webhook URL은 **프로젝트 단위로 등록·격리**
* URL 변경 시 관리자 인증을 통한 명시적 등록 절차

### 8.2 발송 서버 격리

* Argos Webhook 발송 서버는 AWS 내부에서 **결과 통보 전용** 으로 운영
* 외부에서 본 서버로 직접 요청 송신 불가
* 발송 대상은 고객사 등록 URL로만 한정

### 8.3 환경 분리

* Live / Test 환경 발송 채널 분리
* 테스트용 결과는 테스트 환경의 등록 URL로만 발송

***

## 9. 로깅 및 감사

### 9.1 발송 단건 로그

모든 Webhook 발송 시도는 다음 정보와 함께 감사 테이블에 적재:

| 항목         | 설명                     |
| ---------- | ---------------------- |
| 발송 식별자     | 단건 고유 ID               |
| 프로젝트 식별자   | Project ID             |
| 발송 시각      | UTC 타임스탬프              |
| 대상 URL     | 고객사 등록 엔드포인트           |
| HTTP 응답 코드 | 200 / 4xx / 5xx        |
| 응답 본문      | 고객사 응답                 |
| 상태         | SUCCESS / FAIL / ERROR |

### 9.2 일별 집계 메트릭

일자별 성공/실패/에러 건수가 별도 메트릭 테이블에 집계됩니다.

### 9.3 재시도 정책

| 단계                  | 정책                     |
| ------------------- | ---------------------- |
| 1차 시도               | 즉시 발송                  |
| 재시도                 | 최대 3회 (지수 백오프)         |
| DLQ / Manual Replay | 실패 건은 별도 도구로 수동 재발송 가능 |

### 9.4 보존

* 발송 감사 로그 보존 기간은 컴플라이언스 요건에 따라 별도 정의

***

## 10. 컴플라이언스

### 10.1 Argos Identity 보유 인증

* **ISO/IEC 27001** — 정보보호관리체계 국제표준 인증

### 10.2 AWS 인프라 인증 (상속)

Webhook 발송 인프라(AWS Lambda, EC2, DynamoDB 등)는 AWS의 다음 인증을 상속:

* SOC 1 / SOC 2 / SOC 3
* ISO 27001 / 27017 / 27018
* PCI-DSS Level 1
* HIPAA Eligible
* FedRAMP Moderate

### 10.3 위·수탁 처리

* 고객사가 Argos에게 KYC 처리를 위탁한 정보는 처리 완료 후 통보(Webhook) 외 목적으로 사용되지 않습니다.
* 통보 후 발송 감사 로그 정리 정책은 별도 처리 합의에 따릅니다.

***

## 부록 A. 용어 정리

| 용어                           | 정의                                      |
| ---------------------------- | --------------------------------------- |
| Webhook                      | 이벤트 발생 시 HTTPS POST로 결과를 통보하는 비동기 콜백 방식 |
| TLS                          | Transport Layer Security                |
| AES-256                      | 256-bit Advanced Encryption Standard    |
| DLQ                          | Dead Letter Queue (실패 메시지 별도 보관 채널)     |
| 지수 백오프 (Exponential Backoff) | 재시도 간격을 점진적으로 늘리는 방식                    |
| Base64                       | 바이너리 → 텍스트 안전 인코딩                       |
| IP 화이트리스트                    | 허용 IP 만 수신·송신 가능하도록 제한하는 정책             |

***

## 부록 B. 권장 통합 가이드

고객사가 Argos Webhook 수신 엔드포인트를 구축할 때 다음을 권장합니다:

1. **HTTPS 전용 엔드포인트 사용** (Let's Encrypt / 상용 인증서)
2. **Argos 발송 IP 범위만 허용** (방화벽/SG 설정)
3. **`X-Webhook-Encrypted: true` 모드 활성** (프로젝트 옵션에서 데이터 암호화 활성)
4. **수신 즉시 200 OK 응답** 후 비동기 처리 (3초 이상 지연 시 재시도 발생 가능)
5. **멱등성(Idempotency) 처리**: 동일 `submissionId`에 대해 중복 수신 시에도 안전한 처리 보장

***

## 부록 C. 문의

본 문서에 대한 기술적 질의는 Argos Identity 영업/기술 지원 채널로 연락주시기 바랍니다.