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

웹훅이 실패하는 이유와 해결 방법

방금 결제 제공업체의 웹훅을 통합하여 앱에서 주문 상태를 업데이트했습니다. 테스트에서는 모든 것이 작동하지만, 프로덕션에서는 일부 이벤트가 도착하지 않거나 더 심각하게는 중복 이벤트를 받을 수 있습니다. 적절한 안전장치가 없으면 웹훅은 조용한 실패와 보안 허점의 원인이 될 수 있습니다.

웹훅은 이벤트에 의해 트리거되는 HTTP 콜백이지만, 일반적인 API 호출과 달리 푸시 기반이며 비동기적입니다. 이로 인해 두 가지 핵심 과제가 발생합니다: 진위 확인과 전달 보장입니다. 이 가이드에서는 서명된 페이로드와 스마트 재시도를 통해 두 가지 모두를 해결해 보겠습니다.

웹훅이란 무엇인가?

웹훅은 사용자가 정의한 HTTP 콜백입니다. 소스 시스템(예: 새 결제)에서 이벤트가 발생하면, 이벤트 데이터를 포함한 HTTP POST 요청을 사용자가 제공한 URL로 보냅니다. 이를 통해 폴링 없이 실시간으로 반응할 수 있습니다.

일반적인 사용 사례로는 결제 알림, CI/CD 트리거, 채팅 통합 등이 있습니다. 그러나 웹훅은 공용 인터넷을 통해 전송되므로 스푸핑 및 손실에 취약합니다.

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

웹훅이 실제로 제공업체에서 온 것인지 어떻게 알 수 있을까요? 공유 비밀 키로 페이로드에 서명하면 무결성과 진위를 보장할 수 있습니다.

HMAC 서명 작동 방식

제공업체는 비밀 키를 사용하여 요청 본문의 HMAC(예: SHA-256)을 계산하고, 서명을 헤더(예: 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');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

모범 사례:

• 웹훅 엔드포인트마다 강력하고 고유한 비밀 키를 사용하세요.
• 재전송 공격을 방지하기 위해 서명된 페이로드에 타임스탬프를 포함하고, 몇 분 이상 지난 요청은 거부하세요.
• 전송 중 페이로드를 보호하기 위해 항상 HTTPS를 사용하세요.

안정적인 재시도 구현하기

서명이 있더라도 네트워크 문제나 다운타임으로 인해 웹훅 전달이 실패할 수 있습니다. 제공업체는 일반적으로 지수 백오프로 재시도하지만, 수신 측에서도 재시도를 처리해야 합니다.

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

재시도는 중복 처리를 초래할 수 있습니다. 멱등성 키(종종 페이로드나 헤더에 포함됨)를 사용하여 각 이벤트가 정확히 한 번만 처리되도록 하세요. 처리된 이벤트 ID를 저장하고 중복을 무시하세요.

// 예제: 멱등성 웹훅 핸들러
const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const eventId = req.body.id;
  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  // 이벤트 처리...
  processedEvents.add(eventId);
  res.status(200).send('OK');
});

수신자 측 재시도 전략

처리에 실패하면 5xx 상태로 응답하여 제공업체의 재시도를 유도하세요. 일시적인 오류의 경우 자체 재시도 큐를 백오프와 함께 구현할 수도 있습니다.

웹훅 모니터링 및 디버깅

모든 수신 웹훅 요청을 헤더와 페이로드와 함께 로깅하세요(민감한 데이터는 마스킹). JSON Formatter와 같은 도구를 사용하여 페이로드를 예쁘게 출력하면 검사가 더 쉬워집니다. 실패한 전달에 대한 알림을 설정하고 재시도 횟수를 추적하세요.

FAQ

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

서명된 페이로드에는 요청이 신뢰할 수 있는 소스에서 왔으며 변조되지 않았음을 확인하는 암호화 서명(일반적으로 HMAC)이 포함됩니다.

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

대부분의 제공업체는 지수 백오프를 사용하여 3~5회 재시도합니다. 수신자로서 적절한 상태 코드로 응답하고 제공업체가 재시도를 처리하도록 하세요.

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

아니요—HTTPS는 페이로드를 암호화하고 중간자 공격을 방지하는 데 필수적입니다. 일반 HTTP를 통한 웹훅을 절대 허용하지 마세요.

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