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.
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 영업/기술 지원 채널로 연락주시기 바랍니다.
