1. 문서 개요
1.1 목적
Argos Identity가 고객사에게 검증 결과를 Webhook(콜백) 방식으로 통보하는 채널의 네트워크 통신 구조와 보안 정책을 정리한 자료입니다.
1.2 대상 독자
- 고객사의 정보보호·보안 검토 담당자
- Webhook 수신 엔드포인트를 구축·운영하는 개발팀
- 컴플라이언스 / 감사 부서
1.3 범위
- Argos → 고객사 방향의 Webhook 발송 통신
- 통신 프로토콜, TLS, 페이로드 암호화
- 인증·무결성·재시도·감사
2. 서비스 카테고리 소개
Webhook은 Argos가 KYC 처리 결과(승인 / 거부 / 재요청 등)를 고객사에게 비동기 방식으로 통보하는 채널입니다.
2.1 특징
- 이벤트 기반: 결과 발생 시점에 즉시 발송 (폴링 불필요)
- HTTPS 표준 준수: 고객사가 별도 SDK 설치 없이 표준 HTTP 서버로 수신 가능
- 2단계 파이프라인 구조:
- 이벤트 수렴 계층 (서버리스): 발송 대상 결정 + 본문 구성
- 발송 실행 계층 (전용 발송 서버): 고객사 엔드포인트로 HTTPS POST 실행
2.2 발송 트리거
| 이벤트 | 발송 시점 |
|---|
| 검증 완료 | Liveform / Restful API에서 결과 확정 직후 |
| 검증 상태 변경 | 재검증 요청, 보완 요청 발생 시 |
| 관리자 작업 | 대시보드에서 수동 승인/거부 작업 발생 시 |
3. 네트워크 통신 흐름
3.1 전체 흐름
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, 평문 모드 기준)
{
"projectId": "<프로젝트 식별자>",
"submissionId": "<제출 식별자>",
"userId": "<선택>",
"status": "approved | rejected | incomplete",
"timestamp": "<발송 시각>",
"webhookParams": { ... }
}
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 인코딩된 암호문 전송) |
X-Webhook-Encrypted 헤더 확인- 본문(Base64 디코드 → 암호문) 획득
- 프로젝트 API Key를 시드로 키 도출
- AES-256 복호화 → JSON 파싱
6. 인증 및 인가
6.1 고객사 측 발송자 검증 옵션
| 방식 | 설명 |
|---|
| TLS 인증서 + 발송 도메인 검증 | 고객사가 Argos 발송 도메인의 인증서를 통해 출발지 검증 |
| IP 화이트리스트 (권장) | Argos 발송 서버의 고정 IP 범위만 수신 허용 (고객사 방화벽 설정) |
| 암호화 모드 헤더 | X-Webhook-Encrypted: true 검증 및 복호화 가능 여부로 출처 확인 |
| 고객사 등록 인증 헤더 | 협의 시 Argos가 고객사 지정 인증 헤더(예: Bearer 토큰)를 함께 송신 |
강력한 발송자 검증이 필요한 고객사는 IP 화이트리스트 + 페이로드 암호화 모드 의 조합 사용을 권장합니다.
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 수신 엔드포인트를 구축할 때 다음을 권장합니다:
- HTTPS 전용 엔드포인트 사용 (Let’s Encrypt / 상용 인증서)
- Argos 발송 IP 범위만 허용 (방화벽/SG 설정)
X-Webhook-Encrypted: true 모드 활성 (프로젝트 옵션에서 데이터 암호화 활성)- 수신 즉시 200 OK 응답 후 비동기 처리 (3초 이상 지연 시 재시도 발생 가능)
- 멱등성(Idempotency) 처리: 동일
submissionId에 대해 중복 수신 시에도 안전한 처리 보장
부록 C. 문의
본 문서에 대한 기술적 질의는 Argos Identity 영업/기술 지원 채널로 연락주시기 바랍니다.
