Webhook

​

1. 문서 개요

​

1.1 목적

​

1.2 대상 독자

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

​

1.3 범위

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

​

2. 서비스 카테고리 소개

​

2.1 특징

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

​

2.2 발송 트리거

​

3. 네트워크 통신 흐름

​

3.1 전체 흐름

​

3.2 외부 송신 채널

​

4. 통신 프로토콜 및 규약

​

4.1 전송 계층

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

​

4.2 요청 헤더

​

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

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

​

5. 데이터 암호화

​

5.1 전송 중 암호화 (필수)

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

​

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

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

​

6. 인증 및 인가

​

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

​

6.2 ARGOS 내부 인증

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

​

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

​

8. 접근 통제 및 격리

​

8.1 발송 대상 격리

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

​

8.2 발송 서버 격리

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

​

8.3 환경 분리

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

​

9. 로깅 및 감사

​

9.1 발송 단건 로그

​

9.2 일별 집계 메트릭

​

9.3 재시도 정책

​

9.4 보존

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

​

10. 컴플라이언스

​

10.1 Argos Identity 보유 인증

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

​

10.2 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. 용어 정리

​

부록 B. 권장 통합 가이드

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

​

부록 C. 문의