웹훅 완벽 가이드: 서명된 페이로드와 재시도
결제 제공업체의 웹훅을 연동하여 거래 업데이트를 받는다고 가정해 봅시다. 테스트에서는 모든 것이 잘 작동하지만, 프로덕션에서는 트래픽이 몰릴 때 이벤트가 누락되거나 제공업체가 재시도할 때 중복 청구가 발생하는 것을 발견할 수 있습니다. 웹훅은 개념적으로는 간단하지만 실제로는 까다롭습니다. 네트워크 경계를 넘나들고, 지연되거나 중복되거나 위조될 수 있기 때문입니다. 이 글에서는 서명된 페이로드와 스마트한 재시도 전략을 사용하여 견고한 웹훅 소비자와 생산자를 구축하는 방법을 설명합니다.
웹훅이란 무엇인가?
웹훅은 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백입니다. 소스 시스템에서 어떤 일이 발생하면(예: 새 주문) 사용자가 제공한 URL로 HTTP POST 요청을 보냅니다. 폴링과 달리 웹훅은 거의 실시간으로 데이터를 푸시하여 지연 시간과 서버 부하를 줄입니다.
그러나 웹훅은 요청이 실제로 예상 발신자로부터 왔는지 확인하고, 실패를 우아하게 처리하며, 중복 처리를 피하는 등의 과제를 안고 있습니다.
서명된 페이로드로 웹훅 보안 강화
검증 없이는 누구나 웹훅 엔드포인트로 가짜 요청을 보낼 수 있습니다. 서명된 페이로드는 검증할 수 있는 암호화 서명을 포함하여 이 문제를 해결합니다.
HMAC 서명 작동 방식
발신자는 공유 비밀과 요청 본문을 사용하여 해시 기반 메시지 인증 코드(HMAC)를 계산합니다. 서명은 헤더(예: X-Signature)로 전송됩니다. 수신 측에서 HMAC을 다시 계산하여 비교합니다.
// Node.js 예제: 웹훅 서명 검증
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
타이밍 공격을 방지하려면 항상 timingSafeEqual과 같은 상수 시간 비교 함수를 사용하세요.
타임스탬프 포함
재전송 공격을 방지하려면 서명된 페이로드에 타임스탬프를 포함하고 몇 분(예: 5분)보다 오래된 요청은 거부하세요. 타임스탬프는 서명된 데이터의 일부여야 합니다.
안정적인 재시도 구현
네트워크 문제나 일시적인 서버 오류로 인해 웹훅 전송이 실패할 수 있습니다. 견고한 발신자는 지수 백오프를 사용하여 실패한 전송을 재시도합니다.
재시도 전략
- 지수 백오프: 각 재시도 사이에 더 오래 기다립니다(예: 1초, 2초, 4초, 8초...).
- 최대 재시도 횟수: 무한 루프를 피하기 위해 제한을 설정합니다(예: 5회).
- 데드 레터 큐: 최대 재시도 후 이벤트를 저장하여 수동으로 검사할 수 있도록 합니다.
- 멱등성: 수신자가 중복을 제거할 수 있도록 고유한 이벤트 ID를 포함합니다.
예제: Python에서 백오프를 사용한 재시도
import time
import requests
from requests.exceptions import RequestException
def send_webhook(url, payload, max_retries=5):
for attempt in range(max_retries):
try:
response = requests.post(url, json=payload, timeout=5)
if response.status_code < 500:
return True # 성공 또는 클라이언트 오류 (재시도 안 함)
except RequestException:
pass
time.sleep(2 ** attempt) # 지수 백오프
return False
웹훅 소비자를 위한 모범 사례
- 빠르게 응답: 처리하기 전에 2xx 상태로 수신을 확인합니다. 작업은 비동기적으로 큐에 넣습니다.
- 서명 검증: 페이로드를 신뢰하기 전에 항상 서명을 검증합니다.
- 중복 처리: 이벤트 ID를 사용하여 멱등 처리를 보장합니다.
- 모든 것 기록: 디버깅을 위해 수신된 웹훅 로그를 유지합니다.
비교: 웹훅 vs 폴링
| 측면 | 웹훅 | 폴링 |
|---|---|---|
| 지연 시간 | 거의 실시간 | 간격에 따라 다름 |
| 서버 부하 | 낮음 (푸시만) | 높음 (빈번한 요청) |
| 복잡성 | 높음 (엔드포인트, 보안 필요) | 낮음 |
| 안정성 | 재시도 필요 | 본질적으로 재시도됨 |
자주 묻는 질문
서명된 웹훅 페이로드란 무엇인가?
서명된 페이로드는 수신자가 요청의 진위와 무결성을 검증할 수 있도록 암호화 서명(일반적으로 HMAC)을 포함합니다.
실패한 웹훅을 몇 번 재시도해야 하나?
일반적으로 지수 백오프를 사용하여 3~5회 재시도하지만, SLA와 이벤트의 중요성에 따라 달라집니다.
HTTPS 없이 웹훅을 사용할 수 있나?
아니요, 페이로드와 서명이 가로채지지 않도록 항상 HTTPS를 사용하세요. 일반 HTTP는 민감한 데이터를 노출합니다.
웹훅 페이로드를 디버깅할 때 JSON 형식을 빠르게 지정해야 할 수 있습니다. JSON Formatter를 사용하여 JSON 응답을 예쁘게 출력하고 유효성을 검사해 보세요.