웹훅 완벽 가이드: 서명된 페이로드와 재시도로 안정적인 통합 구현하기

Backend2026-11-13TryQuickToolBox

결제 제공업체로부터 웹훅을 받을 엔드포인트를 방금 구축했습니다. 첫 번째 테스트는 잘 작동하지만, 프로덕션에서는 누락된 이벤트, 중복 청구, 요청이 진짜인지 확인할 방법이 없다는 것을 알게 됩니다. 웹훅은 개념적으로 간단하지만 제대로 구현하기는 까다롭습니다. 이 가이드에서는 서명된 페이로드로 웹훅을 보호하고 강력한 재시도 로직을 구현하여 통합이 조용히 중단되지 않도록 하는 방법을 설명합니다.

웹훅이란 무엇이며 왜 중요한가

웹훅은 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백입니다. 애플리케이션이 변경 사항을 확인하기 위해 API를 폴링하는 대신, 서비스가 이벤트 발생 시 데이터를 엔드포인트로 푸시합니다. 이는 통합을 효율적이고 거의 실시간으로 만듭니다.

일반적인 사용 사례로는 결제 알림(예: Stripe), CI/CD 트리거(예: GitHub), 메시징 플랫폼(예: Slack)이 있습니다. 하지만 이 푸시 모델에서는 요청이 언제 도착하는지 제어할 수 없습니다. 따라서 보안과 안정성을 명시적으로 처리해야 합니다.

보안 문제: 서명되지 않은 웹훅은 위험합니다

서명되지 않은 웹훅은 공개 URL로 전송되는 HTTP POST에 불과합니다. 누구나 결제 제공업체에서 온 것처럼 보이는 요청을 보낼 수 있습니다. 검증 없이는 공격자가 이벤트를 위조하여 사기 주문, 데이터 유출 또는 무단 작업을 초래할 수 있습니다.

해결책은 페이로드에 서명하는 것입니다. 발신자는 공유 비밀을 사용하여 요청 본문에 대한 암호화 서명을 계산하고 헤더에 포함합니다. 엔드포인트는 서명을 다시 계산하고 비교합니다. 일치하면 요청이 진짜이며 변조되지 않았음을 알 수 있습니다.

HMAC으로 웹훅 페이로드에 서명하는 방법

HMAC(해시 기반 메시지 인증 코드)은 웹훅 서명의 표준입니다. 비밀 키와 해시 함수(예: SHA-256)를 사용하여 페이로드와 비밀에 고유한 서명을 생성합니다.

다음은 Python에서 발신자가 페이로드에 서명하는 방법입니다:

import hmac
import hashlib
import json

secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# 헤더에 서명 포함: X-Signature: 

수신 측에서는 페이로드를 처리하기 전에 서명을 검증해야 합니다:

import hmac
import hashlib

def verify_signature(payload, received_signature, secret):
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

중요: 타이밍 공격을 방지하려면 항상 hmac.compare_digest와 같은 상수 시간 비교 함수를 사용하세요. 또한 JSON 직렬화가 다를 수 있으므로 구문 분석된 버전이 아닌 원시 요청 본문에 대해 서명을 검증하세요.

서명된 페이로드 모범 사례

실패 처리: 재시도와 멱등성

웹훅은 실패할 수 있습니다: 서버가 다운되거나, 네트워크가 끊기거나, 엔드포인트가 오류를 반환할 수 있습니다. 안정적인 발신자는 전달을 재시도하지만, 수신자는 중복 및 순서가 뒤바뀐 이벤트를 처리하도록 설계해야 합니다.

재시도 전략

대부분의 웹훅 제공업체는 지터를 포함한 지수 백오프를 사용합니다. 예를 들어 1분 후, 5분 후, 30분 후에 재시도하며 최대 시도 횟수까지 반복합니다. 이는 시스템이 과부하되지 않고 복구할 시간을 줍니다.

발신 측을 구축하는 경우 예약된 재시도를 포함한 큐를 구현하세요. 페이로드와 시도 횟수를 저장하고 작업자를 사용하여 재시도를 처리하세요.

멱등성: 안전한 재시도의 핵심

재시도로 인해 중복 전달이 발생할 수 있으므로 엔드포인트는 멱등적이어야 합니다. 즉, 동일한 이벤트를 여러 번 처리해도 한 번 처리한 것과 같은 효과를 가져야 합니다.

일반적인 접근 방식:

다음은 Python에서 간단한 멱등성 검사입니다:

def process_event(event_id, payload):
    if db.exists('processed_events', event_id):
        return  # 이미 처리됨
    # 페이로드 처리
    db.insert('processed_events', event_id)

경쟁 조건을 피하기 위해 검사와 처리가 단일 트랜잭션에서 이루어지도록 하세요.

비교: 폴링 vs. 웹훅

측면폴링웹훅
지연 시간간격에 따라 다름 (예: 5분)거의 실시간
서버 부하변경 사항이 없어도 지속적인 요청이벤트 발생 시에만 요청
복잡성구현하기 간단서명, 재시도, 멱등성 필요
안정성재시도 제어 가능발신자의 재시도 정책에 의존

단계별: 안전한 웹훅 수신기 구현

  1. POST 요청을 수락하고 원시 본문을 읽는 HTTPS 엔드포인트 설정
  2. 서명 헤더(예: X-Signature)와 타임스탬프 헤더(있는 경우) 추출
  3. HMAC과 비밀을 사용하여 서명 검증. 유효하지 않으면 거부
  4. 타임스탬프 확인으로 재전송 공격 방지 (예: 5분보다 오래된 경우 거부)
  5. 페이로드 구문 분석 및 이벤트 ID 추출
  6. 데이터베이스에서 이벤트 ID를 조회하여 멱등성 확인
  7. 이벤트 ID를 기록하는 트랜잭션 내에서 이벤트 처리
  8. 수신 확인을 위해 빠르게 2xx 상태 반환. 처리가 오래 걸리면 작업을 큐에 넣고 202 Accepted 반환

웹훅 구현 테스트

ngrok과 같은 도구를 사용하여 로컬 서버를 노출하고 웹훅을 시뮬레이션하세요. 서명 검증, 멱등성, 재시도 로직에 대한 단위 테스트를 작성하세요. 예를 들어 중복 이벤트 ID가 무시되고 잘못된 서명이 401을 반환하는지 테스트하세요.

디버깅 시 수신된 페이로드와 서명을 로그에 기록하세요(단, 비밀은 절대 로그에 남기지 마세요). JSON 페이로드로 작업하는 경우 JSON 포맷터를 사용하면 구조를 빠르게 검사하고 검증할 수 있습니다.

FAQ

서명된 웹훅 페이로드란 무엇인가요?

서명된 페이로드는 공유 비밀을 사용하여 요청 본문에 대해 계산된 암호화 서명(일반적으로 HMAC)을 포함합니다. 수신자는 서명을 검증하여 요청이 진짜이고 변경되지 않았는지 확인합니다.

웹훅은 몇 번 재시도해야 하나요?

보편적인 숫자는 없지만 일반적인 관행은 지수 백오프를 사용하여 3~5회 재시도하는 것입니다. 그 후 이벤트는 종종 실패로 표시되며 수동 개입이나 데드 레터 큐가 필요할 수 있습니다.

HTTPS 없이 웹훅을 사용할 수 있나요?

일반 HTTP를 통한 웹훅은 절대 사용해서는 안 됩니다. TLS가 없으면 공격자가 페이로드와 서명을 가로채고 요청을 재전송하거나 수정할 수 있습니다. 항상 HTTPS를 사용하세요.

웹훅 페이로드를 검사하고 포맷할 준비가 되셨나요? 무료 JSON 포맷터를 사용하여 JSON 데이터를 즉시 검증하고 보기 좋게 포맷하세요.