웹훅 완벽 가이드: 서명된 페이로드와 재시도 전략

Backend2026-11-12TryQuickToolBox

외부 서비스에 이벤트를 알리기 위해 웹훅을 보내는 API를 구축했습니다. 하지만 수신 엔드포인트가 다운되면 어떻게 될까요? 또는 악의적인 공격자가 웹훅 요청을 위조하려고 하면요? 적절한 보호 장치가 없으면 웹훅은 데이터 불일치와 보안 취약점의 원인이 될 수 있습니다. 이 글에서는 웹훅을 안정적이고 안전하게 만들기 위해 서명된 페이로드와 재시도 메커니즘을 구현하는 방법을 설명합니다.

웹훅이란 무엇이며 왜 보안이 필요한가?

웹훅은 특정 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백입니다. 예를 들어 주문이 발생했을 때 결제 서비스에 알리는 등 시스템 간 실시간 통신을 가능하게 합니다. 그러나 웹훅은 공개적으로 접근 가능한 엔드포인트이기 때문에 스푸핑 및 재전송 공격에 취약합니다. 또한 네트워크 문제나 수신자 다운타임으로 인해 이벤트가 누락될 수 있습니다. 따라서 두 가지 중요한 측면을 해결해야 합니다: 진위성(서명된 페이로드를 통해)과 신뢰성(재시도를 통해)입니다.

서명된 페이로드: 진위성과 무결성 보장

서명된 페이로드를 사용하면 수신자가 웹훅이 신뢰할 수 있는 소스에서 시작되었고 데이터가 변조되지 않았음을 확인할 수 있습니다. 이는 일반적으로 공유 비밀을 사용한 HMAC(해시 기반 메시지 인증 코드)을 통해 달성됩니다.

HMAC 서명 작동 방식

송신자와 수신자는 비밀 키를 공유합니다. 각 웹훅 요청에 대해 송신자는 비밀과 요청 페이로드(종종 재전송 공격을 방지하기 위해 타임스탬프 포함)를 사용하여 HMAC 서명을 계산합니다. 서명은 X-Signature와 같은 헤더로 전송됩니다. 수신자는 서명을 다시 계산하고 수신된 서명과 비교합니다. 일치하면 요청이 진본입니다.

다음은 HMAC-SHA256을 사용한 Python 예제입니다:

import hmac
import hashlib
import time

secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()

# Send headers: X-Signature: signature, X-Timestamp: timestamp

수신자 측에서는 서명을 확인하고 타임스탬프를 검사하여 요청이 최근 것인지(예: 5분 이내) 확인합니다. 이렇게 하면 재전송 공격을 방지할 수 있습니다.

서명된 페이로드 모범 사례

재시도 메커니즘: 안정적인 전달 보장

서명된 페이로드가 있더라도 네트워크 장애나 수신자 오류로 인해 웹훅 전달이 실패할 수 있습니다. 강력한 재시도 전략은 수신자에게 과부하를 주지 않으면서 이벤트가 최종적으로 전달되도록 보장합니다.

재시도 정책 설계

일반적인 접근 방식은 지터를 사용한 지수 백오프입니다. 예를 들어 1분 후, 5분 후, 30분 후에 재시도하고 최대 시도 횟수(예: 5회)까지 수행합니다. 수신자가 중복 제거를 할 수 있도록 페이로드에 고유한 이벤트 ID를 포함하세요.

재시도 일정 예시:

시도지연
1즉시
21분
35분
430분
52시간

재시도를 모두 소진한 후에는 이벤트를 데드 레터 큐로 이동하여 수동으로 검사하세요.

멱등성: 중복 전달 처리

재시도로 인해 중복 전달이 발생할 수 있으므로 수신자는 멱등성을 가져야 합니다. 페이로드에 이벤트 ID를 포함하고 수신자가 처리된 ID를 저장하여 중복을 무시하도록 하세요. 또는 작업을 자연스럽게 멱등적으로 설계하세요(예: POST 대신 PUT 사용).

웹훅 구현: 단계별 가이드

  1. 이벤트 및 페이로드 구조 정의: 시스템이 내보내는 이벤트와 각 이벤트의 JSON 스키마를 문서화하세요.
  2. 비밀 생성: 웹훅 엔드포인트마다 고유한 비밀을 생성하고 안전하게 공유하세요.
  3. 각 요청 서명: 페이로드와 타임스탬프에 대해 HMAC을 계산하고 헤더에 포함하세요.
  4. 백오프를 사용한 재시도 구현: 큐 시스템을 사용하여 재시도를 예약하세요.
  5. 서명 확인 방법 제공: 수신자를 위한 확인 프로세스를 문서화하세요.
  6. 모니터링 및 로깅: 디버깅을 위해 전달 시도와 실패를 추적하세요.

일반적인 함정과 피하는 방법

자주 묻는 질문

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

서명된 웹훅 페이로드에는 수신자가 송신자의 진위성과 데이터 무결성을 확인할 수 있도록 암호화 서명(예: HMAC)이 포함되어 있습니다.

실패한 웹훅을 몇 번 재시도해야 하나요?

일반적으로 지수 백오프를 사용하여 3~5회 재시도합니다. 정확한 횟수는 SLA와 이벤트의 중요도에 따라 다릅니다.

웹훅 서명에 HMAC 대신 JWT를 사용할 수 있나요?

예, JWT를 사용할 수 있지만 HMAC이 더 간단하고 웹훅 서명에 더 일반적입니다. JWT는 오버헤드가 추가되며 인증 토큰에 더 적합합니다.

웹훅 페이로드를 테스트할 준비가 되셨나요? JSON 포매터를 사용하여 보내기 전에 JSON 페이로드를 검증하고 보기 좋게 정리하세요.