웹훅 완벽 가이드: 서명된 페이로드와 재시도
API를 구축했고 이제 이벤트가 발생할 때 다른 서비스에 알려야 합니다. 폴링은 비효율적이므로 웹훅을 구현합니다. 하지만 곧 깨닫게 됩니다: 페이로드가 진짜인지 어떻게 확인할까? 수신자가 다운되면 어떻게 할까? 적절한 보호 장치가 없으면 웹훅은 보안 허점이자 안정성 악몽이 될 수 있습니다.
이 글에서는 웹훅의 필수 요소를 살펴보며, 특히 보안을 위한 서명된 페이로드와 안정성을 위한 재시도 메커니즘에 초점을 맞춥니다. 견고한 웹훅 시스템을 구축하는 데 도움이 되는 실용적인 코드 예제와 모범 사례를 제공합니다.
웹훅이란?
웹훅은 사용자 정의 HTTP 콜백입니다. 특정 이벤트가 발생할 때 한 시스템이 다른 시스템으로 실시간 데이터를 보낼 수 있게 합니다. 데이터를 가져오는 API와 달리 웹훅은 데이터를 푸시합니다. 따라서 이벤트 기반 아키텍처에 이상적입니다.
일반적인 사용 사례로는 결제 알림(예: Stripe), CI/CD 트리거(예: GitHub), 메시징 플랫폼(예: Slack)이 있습니다. 발신자는 수신자가 제공한 URL로 HTTP POST 요청을 보내며, 페이로드에는 이벤트 세부 정보가 포함됩니다.
서명된 페이로드로 웹훅을 보호해야 하는 이유
웹훅 엔드포인트는 공개적으로 접근 가능하므로 스푸핑에 취약합니다. 공격자가 가짜 페이로드를 보내 의도하지 않은 작업을 트리거할 수 있습니다. 이를 방지하기 위해 발신자는 공유 비밀을 사용하여 페이로드에 서명합니다. 수신자는 서명을 검증하여 진위성과 무결성을 확인합니다.
서명은 일반적으로 비밀 키를 사용하여 페이로드의 HMAC(해시 기반 메시지 인증 코드)을 생성하는 것을 포함합니다. 서명은 헤더(예: X-Signature)로 전송됩니다. 수신자는 HMAC을 다시 계산하고 수신된 서명과 비교합니다.
서명된 페이로드 구현 방법
Flask를 사용한 Python의 간단한 예제를 살펴보겠습니다. 발신자는 서명을 계산합니다:
import hmac
import hashlib
import json
import requests
secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)
수신자는 서명을 검증합니다:
from flask import Flask, request, abort
import hmac
import hashlib
app = Flask(__name__)
secret = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
body = request.get_data()
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
# Process payload
return '', 200
모범 사례:
- 강력한 비밀을 사용하고 주기적으로 교체하세요.
- 재전송 공격을 방지하기 위해 서명된 데이터에 타임스탬프를 포함하세요.
- 일정 시간 비교를 위해
hmac.compare_digest를 사용하세요. - 불일치를 피하기 위해 파싱된 JSON이 아닌 원시 본문에 서명하세요.
신뢰할 수 있는 재시도 구현
웹훅 전달은 네트워크 문제, 수신자 다운타임 또는 처리 오류로 인해 실패할 수 있습니다. 견고한 시스템은 지수 백오프를 사용하여 실패한 전달을 재시도해야 합니다.
재시도 전략
일반적인 접근 방식: 증가하는 지연(예: 1초, 5초, 30초, 5분, 30분)으로 최대 N회 재시도합니다. 재시도를 모두 소진하면 전달을 실패로 표시하고 경고합니다.
requests 라이브러리와 tenacity를 사용한 Python의 간단한 재시도 메커니즘입니다:
from tenacity import retry, stop_after_attempt, wait_exponential
import requests
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
headers = {'X-Signature': signature}
response = requests.post(url, json=payload, headers=headers, timeout=10)
response.raise_for_status()
return response
재시도 모범 사례:
- 수신자가 중복 제거할 수 있도록 멱등성 키를 사용하세요.
- 요청이 멈추지 않도록 각 요청에 타임아웃을 설정하세요.
- 디버깅을 위해 각 시도를 기록하세요.
- 대시보드에서 수동으로 재시도할 수 있는 방법을 제공하세요.
비교: 서명된 페이로드 vs 기본 인증
| 접근 방식 | 보안 | 복잡성 | 재전송 보호 |
|---|---|---|---|
| 기본 인증 | 낮음 (매번 자격 증명 전송) | 낮음 | 없음 |
| 서명된 페이로드 (HMAC) | 높음 | 중간 | 예 (타임스탬프 포함) |
단계별: 재시도 기능이 있는 웹훅 발신자 구축
- 이벤트 페이로드를 정의하고 고유한 이벤트 ID와 타임스탬프를 포함하세요.
- 원시 본문에 대해 HMAC-SHA256을 사용하여 서명을 계산하세요.
- 헤더에 서명을 포함하여 요청을 전송하세요.
- 지수 백오프로 재시도하여 실패를 처리하세요.
- 전달을 기록하고 가시성을 제공하세요.
웹훅 테스트
ngrok과 같은 도구를 사용하여 로컬 서버를 노출하고 웹훅 전달을 테스트하세요. 테스트에서 항상 서명을 검증하여 문제를 조기에 발견하세요.
자주 묻는 질문
웹훅에서 서명된 페이로드란 무엇인가요?
서명된 페이로드는 발신자가 공유 비밀을 사용하여 생성한 암호화 서명(보통 HMAC)을 포함하는 웹훅 요청입니다. 수신자는 서명을 검증하여 요청이 진짜이고 변조되지 않았음을 확인합니다.
실패한 웹훅을 몇 번 재시도해야 하나요?
정해진 횟수는 없지만 일반적인 관행은 지수 백오프를 사용하여 3~5회 재시도하는 것입니다. 수신자의 일반적인 다운타임과 이벤트의 중요성을 고려하세요. 항상 수동 재시도를 허용하세요.
웹훅 서명에 JWT를 사용할 수 있나요?
예, JWT를 사용할 수 있지만 더 복잡합니다. HMAC 서명은 더 간단하고 대부분의 경우 충분합니다. 클레임을 포함해야 하는 경우 JWT가 적합할 수 있습니다.
웹훅 페이로드를 테스트할 준비가 되셨나요? JSON Formatter를 사용하여 전송하기 전에 JSON 페이로드를 검증하고 예쁘게 출력하세요.