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

웹훅을 엔드포인트로 보내는 타사 서비스를 방금 통합했습니다. 테스트에서는 모든 것이 잘 작동하지만, 프로덕션에서는 이벤트 누락, 중복 전달, 때때로 보안 문제를 발견하게 됩니다. 웹훅은 개념적으로는 간단하지만 실제로는 까다롭습니다. 특히 진위 여부를 확인하고 실패를 처리할 때 더욱 그렇습니다.

이 가이드에서는 서명된 페이로드로 웹훅을 보호하고 강력한 재시도 메커니즘을 구현하여 신뢰할 수 있는 통합을 구축하는 방법을 설명합니다.

웹훅이란?

웹훅은 사용자가 정의한 HTTP 콜백입니다. 소스 시스템에서 이벤트가 발생하면(예: 결제 완료) 해당 이벤트에 대한 데이터를 포함하여 사용자가 지정한 URL로 HTTP POST 요청을 보냅니다. 이를 통해 폴링 없이 서비스 간 실시간 통신이 가능합니다.

그러나 웹훅은 과제를 안고 있습니다. 요청이 정말로 예상 발신자로부터 온 것인지 어떻게 알 수 있을까요? 엔드포인트가 일시적으로 다운되면 어떻게 될까요? 바로 여기에서 서명된 페이로드와 재시도가 필요합니다.

서명된 페이로드로 웹훅 보호하기

서명된 페이로드는 암호화 서명을 사용하여 요청이 발신자로부터 시작되었고 변조되지 않았음을 증명합니다. 일반적인 접근 방식은 공유 비밀을 사용하는 HMAC(해시 기반 메시지 인증 코드)입니다.

HMAC 서명 작동 방식

발신자는 비밀 키를 사용하여 요청 본문(때로는 타임스탬프와 같은 헤더)에 대한 HMAC을 계산합니다. 서명은 헤더(예: X-Signature)로 전송됩니다. 서버는 HMAC을 다시 계산하고 수신된 서명과 비교합니다. 일치하면 요청이 진짜입니다.

다음은 Flask를 사용한 Python의 최소 예제입니다:

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    if not signature:
        abort(400, 'Missing signature')
    body = request.get_data()
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        abort(401, 'Invalid signature')
    # 이벤트 처리
    return '', 200

핵심 사항:

• 타이밍 공격을 방지하려면 항상 상수 시간 비교 함수(예: hmac.compare_digest)를 사용하세요.
• 재전송 공격을 방지하려면 서명된 데이터에 타임스탬프를 포함하고, 몇 분 이상 지난 요청은 거부하세요.
• 비밀을 안전하게 유지하세요. 클라이언트 측에 절대 노출하지 마세요.

추가 보안 조치

• HTTPS: 전송 중 페이로드를 보호하려면 항상 HTTPS를 사용하세요.
• IP 허용 목록: 제공자가 IP 범위를 게시하는 경우 해당 IP로 요청을 제한하세요.
• 멱등성: 재시도로 인해 중복이 발생할 수 있으므로 이벤트 ID를 사용하여 중복을 제거하세요.

신뢰할 수 있는 재시도 구현

웹훅 소비자는 실패할 수 있습니다. 서버가 다운되거나 처리 시간이 초과될 수 있습니다. 발신자는 지수 백오프를 사용하여 실패한 전달을 재시도해야 합니다. 소비자는 재시도를 우아하게 처리해야 합니다.

발신자 측 (웹훅 시스템을 구축하는 경우)

1. 빠르게 2xx 반환: 시간 초과를 피하기 위해 처리 전에 수신을 확인하세요. 비동기 작업에는 큐를 사용하세요.
2. 실패 시 재시도: 시간 초과(예: 5초) 내에 2xx를 받지 못하면 지연 시간을 늘려가며 재시도하세요(예: 1초, 5초, 30초, 5분, 30분).
3. 재시도 제한: 최대 시도 횟수(예: 5회) 후에는 전달을 실패로 표시하고 알림을 보내세요.
4. 고유 이벤트 ID 포함: 소비자가 중복을 제거할 수 있도록 하세요.

소비자 측 (귀하의 엔드포인트)

• 빠르게 응답: 즉시 2xx를 반환하고 필요한 경우 비동기적으로 처리하세요.
• 멱등성 유지: 이벤트 ID를 사용하여 동일한 이벤트를 두 번 처리하지 않도록 하세요.
• 중복 처리: 처리된 이벤트 ID를 합리적인 기간 동안 저장하세요.
• 실패 기록: 처리에 실패하면 5xx를 반환하여 재시도를 트리거하되, 루프에 빠지지 않도록 주의하세요.

비교: 서명된 페이로드 vs. 기본 인증

로컬에서 웹훅 테스트하기

개발 중에는 웹훅을 수신할 공개 URL이 필요합니다. ngrok 또는 localtunnel과 같은 도구를 사용하면 로컬 서버를 노출할 수 있습니다. 항상 시뮬레이션된 실패로 서명 검증 및 재시도 동작을 테스트하세요.

웹훅 페이로드를 검사할 때 가독성을 위해 JSON 형식을 지정해야 할 수 있습니다. JSON Formatter를 사용하면 JSON 본문을 예쁘게 인쇄하고 유효성을 검사할 수 있습니다.

FAQ

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

서명된 페이로드에는 수신자가 요청의 진위성과 무결성을 확인할 수 있도록 암호화 서명(종종 HMAC)이 포함됩니다.

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

고정된 횟수는 없습니다. 일반적인 관행은 지수 백오프를 사용하여 3~10회 재시도하는 것입니다. 핵심은 신뢰성과 리소스 사용량의 균형을 맞추고 지속적인 실패에 대해 알림을 보내는 것입니다.

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

권장하지 않습니다. 서명이 없으면 발신자를 확인할 수 없어 엔드포인트가 스푸핑에 취약해집니다. 프로덕션에서는 항상 서명을 사용하세요.

웹훅 페이로드를 디버깅할 준비가 되셨나요? JSON Formatter를 사용하여 JSON 데이터를 빠르게 검증하고 형식을 지정해 보세요.