웹훅 완벽 가이드: 서명된 페이로드와 재시도
결제 제공업체나 CI/CD 서비스를 연동한 후 실시간 이벤트를 수신해야 하는 상황이 되었습니다. 웹훅은 시스템 간에 데이터를 푸시하는 표준 방식이지만, 많은 구현이 보안 취약점이나 불안정한 전달 때문에 프로덕션에서 실패합니다. 이 가이드에서는 서명된 페이로드로 웹훅을 보호하고 견고한 재시도 메커니즘을 구현하는 방법을 설명합니다.
웹훅이란 무엇이며 왜 중요한가
웹훅은 HTTP 콜백입니다. 소스 시스템에서 이벤트가 발생하면(예: 새 주문) 사용자가 제공한 URL로 HTTP POST 요청을 보냅니다. 폴링과 달리 웹훅은 효율적이고 거의 실시간으로 동작합니다. 하지만 HTTP 기반이기 때문에 보안과 안정성을 명시적으로 처리해야 합니다.
일반적인 사용 사례로는 결제 알림, CI/CD 파이프라인 트리거, 채팅 알림, SaaS 애플리케이션 간 데이터 동기화 등이 있습니다.
서명된 페이로드로 웹훅 보호하기
웹훅은 공개적으로 접근 가능한 엔드포인트이므로 공격자가 위조 요청을 보낼 수 있습니다. 이를 방지하기 위해 제공업체는 비밀 키로 각 페이로드에 서명합니다. 수신자는 서명을 검증하여 진위성과 무결성을 확인합니다.
HMAC 서명의 동작 방식
가장 일반적인 방법은 HMAC-SHA256입니다. 제공업체는 공유 비밀 키를 사용해 요청 본문의 해시를 계산하고 이를 헤더(예: X-Signature)에 포함합니다. 수신자는 해시를 다시 계산하여 비교합니다.
// Node.js 예제: 서명 생성
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// 헤더로 서명 전송: X-Signature: sha256=...
수신자 측에서 서명 검증하기
타이밍 공격을 방지하려면 항상 상수 시간 비교를 사용하세요. Node.js에서는 crypto.timingSafeEqual을 사용합니다.
// Express.js 미들웨어 예제
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // 원본 본문 필요
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
중요: 불일치를 피하려면 파싱된 JSON이 아닌 원본 요청 본문을 사용해 검증하세요.
추가 보안 조치
- 타임스탬프 검증: 서명에 타임스탬프를 포함하고 몇 분 이상 지난 요청은 거부하여 재전송 공격을 방지하세요.
- HTTPS 전용: 전송 중 데이터를 보호하려면 항상 HTTPS 엔드포인트를 사용하세요.
- IP 허용 목록: 제공업체가 IP 대역을 공개하는 경우 해당 IP로 들어오는 요청을 제한하세요.
안정적인 재시도 구현하기
웹훅은 네트워크 문제, 서버 다운타임 또는 버그로 인해 실패할 수 있습니다. 제공업체는 일반적으로 지수 백오프를 사용해 실패한 전달을 재시도합니다. 수신자로서 멱등성을 보장하고 중복 이벤트를 처리해야 합니다.
멱등성을 위한 설계
각 웹훅 이벤트에는 고유 ID가 있어야 합니다. 처리된 ID를 저장하여 중복을 무시하세요. 고유 제약 조건이 있는 데이터베이스나 Redis 같은 캐시를 사용하세요.
// 멱등 처리 의사 코드
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24시간 TTL
재시도 전략
제공업체는 일반적으로 지연 시간을 늘려가며 재시도합니다(예: 1초, 5초, 30초, 5분, 1시간). 타임아웃을 피하려면 엔드포인트가 빠르게(5초 이내) 응답하도록 하세요. 처리가 더 오래 걸리는 경우 수신을 확인하고 비동기적으로 처리하세요.
다음은 일반적인 재시도 패턴 비교입니다:
| 패턴 | 장점 | 단점 |
|---|---|---|
| 고정 간격 | 단순함 | 복구 중인 서버에 부하를 줄 수 있음 |
| 지수 백오프 | 장애 중 부하 감소 | 일시적 오류에 대한 전달 지연 |
| 지터를 적용한 지수 백오프 | 동시 재시도 폭주 방지 | 약간 더 복잡함 |
모니터링과 데드 레터 큐
모든 웹훅 시도와 실패를 로깅하세요. 최대 재시도 횟수에 도달하면 이벤트를 수동 검사를 위해 데드 레터 큐(DLQ)로 이동하세요. 높은 실패율에 대해 알림을 설정하세요.
전체 통합: 단계별 구현
- HTTPS 엔드포인트를 설정하고 POST 요청을 수락하며 원본 본문을 읽습니다.
- 서명을 검증하고 공유 비밀 키와 상수 시간 비교를 사용합니다.
- 타임스탬프를 확인하여 재전송 공격을 방지합니다(제공되는 경우).
- 멱등성을 보장하기 위해 이벤트 ID를 캐시나 데이터베이스와 대조합니다.
- 이벤트를 비동기적으로 처리하고 시간이 걸릴 수 있는 경우 즉시 200 OK로 응답합니다.
- 재시도 로직을 구현하고 송신자 측에서 지수 백오프와 지터를 적용합니다.
- 모니터링 및 알림을 설정하고 지속적인 오류에는 DLQ를 사용합니다.
FAQ
서명된 웹훅 페이로드란 무엇인가요?
서명된 페이로드에는 암호화 서명(보통 HMAC)이 포함되어 있어 수신자가 요청이 신뢰할 수 있는 출처에서 왔으며 변조되지 않았음을 확인할 수 있습니다.
중복된 웹훅 이벤트는 어떻게 처리하나요?
페이로드에 제공된 고유 이벤트 ID를 사용해 처리된 이벤트를 추적하세요. ID를 TTL과 함께 데이터베이스나 캐시에 저장하여 중복을 무시하세요.
웹훅 엔드포인트는 무엇을 반환해야 하나요?
수신을 확인하기 위해 2xx 상태 코드(예: 200 OK)를 빠르게 반환하세요. 처리가 실패하면 재시도를 트리거하기 위해 5xx를 반환하되, 일시적 오류에만 해당합니다.
웹훅 페이로드를 테스트할 때 JSON 구조를 검사해야 할 수 있습니다. JSON Formatter를 사용해 웹훅 페이로드를 검증하고 보기 좋게 출력하면 디버깅이 더 쉬워집니다.