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

방금 결제 게이트웨이나 CI/CD 서비스를 통합했고, 이제 실시간 이벤트를 받아야 합니다. 웹훅은 표준 솔루션이지만 두 가지 중요한 과제가 있습니다. 요청이 실제로 발신자로부터 온 것인지 확인하고, 서버가 일시적으로 사용 불가능한 경우 이벤트가 손실되지 않도록 보장해야 합니다. 이 글에서는 서명된 페이로드와 재시도 메커니즘을 구현하여 견고한 웹훅 수신기를 구축하는 방법을 설명합니다.

웹훅이란?

웹훅은 HTTP 콜백입니다. 애플리케이션이 업데이트를 위해 API를 폴링하는 대신, 이벤트가 발생할 때마다 서비스가 제공한 URL로 HTTP POST 요청을 보냅니다. 이 푸시 모델은 지연 시간과 서버 부하를 줄입니다. 그러나 요청이 외부 서비스에서 시작되므로 신뢰할 수 없는 입력으로 처리해야 합니다.

페이로드에 서명하는 이유

검증 없이는 웹훅 엔드포인트를 발견한 누구나 가짜 이벤트를 보내 권한 없는 작업을 트리거할 수 있습니다. 공유 비밀 키로 페이로드에 서명하면 발신자의 신원을 확인하고 페이로드가 변조되지 않았음을 보장할 수 있습니다. 가장 일반적인 방법은 SHA-256을 사용하는 HMAC(해시 기반 메시지 인증 코드)입니다.

HMAC 서명 작동 방식

발신자는 비밀 키를 사용하여 원시 요청 본문의 HMAC 다이제스트를 계산하고 이를 헤더(예: X-Signature)에 포함합니다. 서버는 동일한 비밀 키로 HMAC을 다시 계산하고 수신된 서명과 비교합니다. 일치하면 요청이 진짜입니다.

// Node.js 예제: 웹훅 서명 검증
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = hmac.digest('hex');
  // 타이밍 공격을 방지하려면 timingSafeEqual을 사용하세요.
  return crypto.timingSafeEqual(
    Buffer.from(digest, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

중요: 타이밍 차이를 통해 정보가 유출되지 않도록 항상 일정 시간 비교 함수(예: timingSafeEqual)를 사용하세요. 또한 재직렬화하면 바이트 시퀀스가 변경될 수 있으므로 구문 분석된 JSON이 아닌 원시 본문에 대해 HMAC을 계산하세요.

재시도 구현

서명이 있더라도 네트워크 문제나 서버 오류로 인해 웹훅 전달이 실패할 수 있습니다. 신뢰할 수 있는 발신자는 일반적으로 지수 백오프를 사용하여 실패한 전달을 재시도합니다. 수신자로서 엔드포인트를 멱등적으로 설계하고 적절한 상태 코드를 반환해야 합니다.

발신자 관점의 재시도 전략

• 5xx 및 네트워크 오류 시 재시도: 일시적인 문제를 나타냅니다.
• 4xx 시 재시도하지 않음: 클라이언트 오류(예: 400 Bad Request)는 일반적으로 영구적이며 재시도해도 도움이 되지 않습니다.
• 지수 백오프 사용: 수신자에게 과부하를 주지 않도록 각 재시도 사이에 더 오래 기다립니다.
• 최대 재시도 횟수 설정: 한도를 초과하면 전달을 실패로 표시하고 경고합니다.

멱등 수신기 설계

재시도로 인해 중복 전달이 발생할 수 있으므로 수신기는 동일한 이벤트를 여러 번 처리해도 부작용이 없어야 합니다. 페이로드(또는 헤더)에 고유한 이벤트 ID를 포함하고 처리된 ID를 저장하세요. 이벤트 ID가 이미 처리된 경우 재처리하지 않고 즉시 200 OK를 반환합니다.

// 멱등 웹훅 처리를 위한 의사 코드
function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return { status: 200, body: 'Already processed' };
  }
  // 이벤트 처리...
  processedEvents.add(event.id);
  return { status: 200, body: 'Success' };
}

웹훅 보안 및 안정성을 위한 모범 사례

• HTTPS 사용: 도청을 방지하려면 항상 TLS를 통해 웹훅 엔드포인트를 제공하세요.
• 타임스탬프 검증: 서명에 타임스탬프가 포함된 경우 재생 공격을 방지하기 위해 몇 분보다 오래된 요청을 거부하세요.
• 빠른 응답: 무거운 처리를 수행하기 전에 2xx 상태로 수신 확인을 보내세요. 작업을 비동기적으로 큐에 넣으세요.
• 모든 것 기록: 문제를 디버깅하기 위해 헤더와 페이로드(민감한 데이터는 삭제)를 포함하여 수신된 웹훅의 로그를 유지하세요.
• 비밀 키 주기적 교체: 원활한 교체를 위해 여러 활성 비밀 키를 지원하세요.

비교: 폴링 vs. 웹훅

FAQ

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

공유 비밀 키를 사용하여 원시 요청 본문의 HMAC을 계산한 다음, 일정 시간 비교 함수를 사용하여 헤더의 서명과 비교합니다.

웹훅 엔드포인트는 무엇을 반환해야 하나요?

이벤트를 수신하면 즉시 2xx 상태 코드(예: 200 OK)를 반환하세요. 4xx 또는 5xx를 반환하면 발신자가 재시도하거나 전달을 실패로 표시할 수 있습니다.

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

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

웹훅 페이로드를 디버깅할 때 JSON 형식 지정은 필수입니다. JSON 포매터를 사용하여 들어오는 JSON 데이터를 빠르게 예쁘게 출력하고 유효성을 검사하세요.