---
type: knowledge
domain: backend
status: active
last-reviewed: 2026-07-27
---

# 외부 연동과 웹훅

> 한 줄 정의
> 외부 API는 "언젠가 반드시 실패하고, 예고 없이 바뀌는 의존성"으로 설계한다. 신뢰성 메커니즘의 채택 기준은 [[백엔드 원리]], 분산 환경 일반론은 [[분산 신뢰성 패턴]] — 여기는 연동 경계에서의 실전 규율이다.

## 호출 측 4계명

1. **타임아웃 예외 없음** — 기본값 방치가 스레드 고갈의 시작이다.
2. 재시도는 멱등한 요청 + 재시도 가치가 있는 실패(5xx·타임아웃, 429는 Retry-After 준수 시)만, 백오프+상한과 함께. 그 외 4xx 재시도는 같은 실패의 반복이다.
3. **응답을 신뢰하지 않는다** — 스키마 검증 후 사용. "문서에 있으니 온다"는 가정이고, null·누락 필드·타입 변경은 현실이다.
4. 장애 시 동작을 미리 결정한다 — 기능 저하(degrade)로 버틸지, 명시적 실패로 알릴지. "생각 안 해둠"이 최악의 선택지다.

## 어댑터 한 겹 — 외부 모델을 도메인에 직결하지 않는다

벤더 응답 구조를 내 도메인 객체로 변환하는 어댑터 계층을 한 겹 둔다.

- 벤더 교체·API 버전 변경의 수정 범위가 어댑터 한 곳으로 갇힌다.
- 벤더의 이상한 네이밍·구조가 코드베이스 전체로 번지는 것을 막는다 (anti-corruption layer).
- API 버전은 고정하고 명시적으로 올린다 — "latest" 추종은 예고 없는 파손이다. 내가 계약을 진화시키는 쪽일 때의 규율은 [[호환성과 계약 진화]].

## 웹훅 수신 4계명

| 계명 | 이유 |
|------|------|
| ① 서명 검증 (HMAC) + 타임스탬프 허용 오차 | 서명 없는 웹훅 엔드포인트는 "누구나 우리 DB에 이벤트를 쓸 수 있는 공개 API"다. 서명이 있어도 타임스탬프 검증이 없으면 가로챈 요청의 재전송(replay)에 뚫린다 |
| ② 검증→저장→2xx, 무거운 처리는 비동기 | 처리를 기다리다 타임아웃 나면 발신자가 재전송 → 중복 폭탄. 단 저장 전에 200부터 주면 유실이다 — 이벤트를 저장(이벤트 ID 유니크)한 뒤 응답하고, 저장 실패면 비-2xx로 재전송을 유도한다 |
| ③ 멱등 소비 — 이벤트 ID 중복 검사 | 웹훅은 **최소 1회 전달**이 계약이다. 같은 이벤트가 언제든 다시 올 수 있다 |
| ④ 순서를 가정하지 않는다 | "생성" 이벤트보다 "갱신" 이벤트가 먼저 도착할 수 있다 — 버전·시퀀스 번호로 판단하고, 없으면 최신 상태를 재조회한다 (발신자 타임스탬프 비교는 최후 수단) |

## 웹훅은 유실된다 — 보정 폴링과 세트

웹훅만 믿는 시스템은 반드시 데이터가 어긋난다 (발신 실패, 수신 다운, 네트워크). 실무 정답은 **웹훅(실시간) + 주기적 보정 폴링(reconciliation)** 조합이다. 폴링이 진실을 맞추고, 웹훅이 지연을 줄인다.

## 결제 연동 특수 규칙

- **금액은 서버가 재계산한다** — 클라이언트가 보낸 금액으로 결제 생성 금지 (가격 조작의 고전).
- 결제 상태의 진실은 **웹훅/조회 API**다 — 클라이언트의 "결제 성공했어요" 콜백은 UX 신호일 뿐 원장이 아니다.
- 중복 결제 방지: 주문 단위 멱등 키.
- 원화 등 금액은 정수(최소 단위)로 다룬다 — 부동소수점 금액은 사고다.

## 발신 측 (내가 웹훅을 제공할 때)

- 재시도 + 백오프 + 최대 횟수, 실패 이벤트는 기록하고 재발송 수단 제공.
- 서명 헤더 제공 (수신자가 검증할 수 있게), 시크릿 로테이션 경로 마련.
- 이벤트 로그를 남겨 "보냈는가"를 논쟁이 아니라 조회로 끝낸다.

## 환경·시크릿 분리

- 샌드박스와 프로덕션의 API 키·엔드포인트·웹훅 URL은 물리적으로 분리 — "테스트 키로 프로덕션 결제"는 유명한 사고 유형이다.
- API 키 권한은 최소로 (읽기만 필요한데 전체 권한 키 발급 금지) → [[보안 원리]] 최소 권한.

## 관련 문서

- [[백엔드 원리]] — Timeout·Retry·멱등성 채택 기준표
- [[분산 신뢰성 패턴]] — 서킷브레이커·격벽 일반론
- [[인증 구현 실전]] — OAuth·API 키 취급
- [[QA 원리]] — 통합 지점은 버그 서식지
- [[00_백엔드 허브]] — 06_백엔드 진입점