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

결제 게이트웨이를 웹훅으로 연동한 직후입니다. 테스트에서는 모든 것이 잘 작동하지만, 프로덕션에서는 이벤트가 누락되거나 중복 알림이 발생해 이중 청구가 일어나기도 합니다. 근본 원인은 대개 서명된 페이로드와 재시도를 처리하는 방식에 있습니다. 이 글에서는 웹훅의 작동 원리를 설명하고, 견고하고 안전한 통합을 구축하기 위한 실용적인 단계를 제시합니다.

웹훅이란 무엇인가?

웹훅은 사용자 정의 HTTP 콜백입니다. 소스 시스템(예: 결제 처리)에서 이벤트가 발생하면, 이벤트 데이터를 포함한 HTTP POST 요청을 지정한 URL로 전송합니다. 폴링과 달리 웹훅은 거의 실시간으로 데이터를 푸시하므로 지연 시간과 서버 부하를 줄입니다.

하지만 웹훅에는 과제가 따릅니다: 진위 확인, 실패 처리, 정확히 한 번 처리 보장. 하나씩 살펴보겠습니다.

서명된 페이로드: 진위 확인

웹훅 엔드포인트는 공개적으로 접근 가능하므로 누구나 가짜 요청을 보낼 수 있습니다. 이를 방지하기 위해 제공자는 비밀 키로 페이로드에 서명합니다. 서명을 검증하여 요청이 진짜인지 확인합니다.

HMAC 서명 작동 방식

대부분의 제공자는 SHA-256과 함께 HMAC(Hash-based Message Authentication Code)을 사용합니다. 제공자는 요청 본문과 공유 비밀 키로 서명을 계산한 뒤 헤더(예: X-Signature)에 포함합니다. 수신 측에서 서명을 다시 계산해 비교합니다.

Python 예제:

import hmac
import hashlib

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

중요: 파싱된 JSON이 아닌 원본 요청 본문을 사용하세요. 파싱 과정에서 공백이 변경되어 서명이 깨질 수 있습니다.

흔한 함정

• 파싱된 데이터 사용: 항상 원본 바이트를 기준으로 검증하세요.
• 타이밍 공격: 상수 시간 비교(예: hmac.compare_digest)를 사용하세요.
• 타임스탬프 무시: 일부 제공자는 재전송 공격을 방지하기 위해 서명에 타임스탬프를 포함합니다. 허용 범위(예: 5분) 내인지 검증하세요.

재시도: 실패를 우아하게 처리하기

엔드포인트가 일시적으로 다운되거나 네트워크 문제로 실패할 수 있습니다. 안정적인 웹훅 시스템은 지수 백오프로 실패한 전송을 재시도합니다.

재시도 전략

제공자는 일반적으로 비 2xx 응답이나 타임아웃 시 재시도합니다. 일반적인 패턴:

수신자로서 발신자의 재시도 정책을 제어할 수는 없지만, 엔드포인트를 탄력적으로 설계할 수 있습니다.

수신자를 위한 모범 사례

1. 빠르게 응답: 몇 초 내에 2xx를 반환하세요. 처리는 백그라운드 작업으로 넘기세요.
2. 멱등성 유지: 페이로드의 멱등성 키를 사용해 중복 처리를 피하세요.
3. 모든 것 로깅: 디버깅과 재처리를 위해 수신 웹훅을 저장하세요.
4. 실패 모니터링: 반복 실패에 대한 알림을 설정하세요.

멱등성 구현

중복은 발생합니다: 응답이 느려서 발신자가 재시도하거나, 동일한 이벤트를 실수로 두 번 처리할 수 있습니다. 멱등성은 이벤트를 여러 번 처리해도 한 번 처리한 것과 같은 효과를 보장합니다.

고유 이벤트 ID(보통 페이로드나 헤더에 제공됨)를 사용하고, 고유 제약 조건과 함께 데이터베이스에 저장하세요. 처리 전에 ID가 존재하는지 확인하고, 존재하면 건너뜁니다.

def process_event(event_id, data):
    if EventLog.exists(event_id):
        return  # already processed
    EventLog.create(event_id)
    # process data...

고처리량 시스템에서는 경쟁 조건을 피하기 위해 분산 잠금이나 데이터베이스 트랜잭션을 사용하세요.

보안 고려 사항

서명 검증 외에도 다음을 고려하세요:

• HTTPS: 도청을 방지하기 위해 항상 TLS를 사용하세요.
• IP 허용 목록: 제공자가 IP 범위를 공개하면 수신 요청을 제한하세요.
• 속도 제한: 엔드포인트를 남용으로부터 보호하세요.
• 페이로드 검증: 서명 검증 후에도 주입 공격을 피하기 위해 데이터 스키마를 검증하세요.

로컬에서 웹훅 테스트하기

개발 중에는 웹훅을 수신할 공개 URL이 필요합니다. ngrok이나 localtunnel 같은 도구가 로컬 서버를 노출합니다. 또는 많은 제공자가 이벤트를 로컬호스트로 전달하는 CLI를 제공합니다.

재시도 처리를 테스트하려면 실패를 시뮬레이션하세요: 의도적으로 500 오류를 반환하고 제공자의 재시도 패턴을 관찰하세요.

FAQ

웹훅 서명은 어떻게 검증하나요?

공유 비밀 키로 HMAC을 사용하세요. 원본 요청 본문의 해시를 계산하고, 상수 시간 비교 함수로 서명 헤더와 비교하세요.

중복 웹훅을 받으면 어떻게 해야 하나요?

이벤트 ID를 저장해 멱등성을 구현하세요. 비즈니스 로직을 실행하기 전에 이벤트가 이미 처리되었는지 확인하세요.

안정성을 위해 웹훅 재시도에만 의존할 수 있나요?

아니요. 재시도는 도움이 되지만 전달을 보장하지는 못합니다. 중요한 이벤트의 경우 웹훅을 폴링 폴백이나 이벤트를 영속화하는 메시지 큐와 결합하세요.

웹훅 페이로드를 디버깅할 때 JSON 데이터를 검사해야 할 수 있습니다. JSON Formatter를 사용해 페이로드를 빠르게 예쁘게 출력하고 검증하세요.