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

Backend2026-11-17TryQuickToolBox

엔드포인트로 웹훅을 보내는 서드파티 서비스를 방금 통합했다고 가정해 봅시다. 테스트에서는 모든 것이 잘 작동하지만, 프로덕션에서는 누락된 이벤트, 중복 전송, 심지어 위조된 요청까지 발견하게 됩니다. 웹훅은 개념은 단순하지만 제대로 구현하기는 까다롭습니다. 이 글에서는 서명된 페이로드로 웹훅을 안전하게 보호하고, 안정적인 재시도 로직을 구현해 통합을 견고하고 신뢰할 수 있게 만드는 방법을 설명합니다.

웹훅이란 무엇이며 왜 중요한가

웹훅은 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백입니다. 변경 사항을 확인하기 위해 API를 폴링하는 대신 URL을 등록하면, 무언가 발생할 때마다 서비스가 이벤트 데이터와 함께 POST 요청을 보냅니다. 이 푸시 모델은 지연 시간과 서버 부하를 줄여 결제 알림, CI/CD 트리거, 채팅 메시지 같은 실시간 통합에 이상적입니다.

하지만 웹훅은 진위 확인, 실패 처리, 정확히 한 번 처리를 보장하는 등의 과제를 안고 있습니다. 하나씩 살펴보겠습니다.

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

검증이 없으면 누구나 웹훅 엔드포인트로 가짜 요청을 보낼 수 있습니다. 서명된 페이로드는 공유 시크릿을 사용해 생성된 암호화 서명을 요청 헤더에 포함시켜 이 문제를 해결합니다. 서명을 검증하면 요청이 예상 발신자로부터 왔고 변조되지 않았음을 확인할 수 있습니다.

HMAC 서명의 작동 방식

대부분의 서비스는 SHA-256과 함께 HMAC(해시 기반 메시지 인증 코드)을 사용합니다. 발신자는 시크릿을 사용해 요청 본문(때로는 타임스탬프)의 해시를 계산하고, 이를 X-Signature 같은 헤더에 포함시킵니다. 수신 측에서는 해시를 다시 계산해 비교합니다.

다음은 Node.js에서의 일반적인 검증 흐름입니다:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

타이밍 공격을 방지하려면 항상 타이밍 안전 비교를 사용하세요. 또한 서명된 데이터에 타임스탬프를 포함시키고, 몇 분 이상 지난 요청은 거부하여 재전송 공격을 방지하세요.

서명 검증 모범 사례

안정적인 재시도 구현하기

네트워크는 실패하고, 서버는 재시작되며, 엔드포인트는 타임아웃됩니다. 견고한 웹훅 시스템은 실패한 전송을 재시도해야 합니다. 하지만 재시도는 중복을 일으킬 수 있으므로 멱등성이 필요합니다.

재시도 전략

대부분의 제공업체는 지터를 포함한 지수 백오프를 사용합니다. 예를 들어 1분 후, 5분 후, 30분 후에 재시도하며, 최대 시도 횟수(예: 5회)까지 진행합니다. 수신자가 중복을 제거할 수 있도록 페이로드에 고유 이벤트 ID를 포함시키세요.

수신 측에서는 수신 확인을 위해 2xx 상태로 신속하게 응답한 후 비동기적으로 처리하세요. 처리가 실패하더라도 발신자가 무한정 재시도할 것이라고 기대할 수 없으므로, 자체적인 데드 레터 큐나 알림을 구현하세요.

멱등성 키

중복 전송을 처리하려면 멱등성 키(흔히 이벤트 ID)를 사용하고, 처리된 ID를 합리적인 기간 동안 저장하세요. 처리 전에 해당 ID가 이미 확인되었는지 검사하고, 그렇다면 재처리 없이 성공을 반환하세요.

// 예시: Express에서의 멱등성 검사
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // 이벤트를 비동기적으로 처리
  res.status(200).send('OK');
});

비교: 폴링 vs 웹훅

측면폴링웹훅
지연 시간높음 (간격 기반)낮음 (거의 실시간)
서버 부하높음 (빈번한 요청)낮음 (이벤트 기반)
복잡성구현이 간단함서명 검증과 재시도 필요
신뢰성폴링 빈도에 의존재시도 메커니즘에 의존

단계별: 안전한 웹훅 수신기 구축하기

  1. 엔드포인트 설정: HTTPS를 통해 POST 요청을 받는 엔드포인트를 만드세요.
  2. 서명 검증: 공유 시크릿으로 서명을 검증하고 잘못된 요청은 401로 거부하세요.
  3. 타임스탬프 확인: 재전송 공격을 방지하세요.
  4. 즉시 응답: 기본 검증 후 200 OK로 응답하고 비동기적으로 처리하세요.
  5. 멱등성 구현: 이벤트 ID를 사용해 중복 처리를 피하세요.
  6. 로깅 및 모니터링: 실패와 재시도를 기록하고 모니터링하세요.

FAQ

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

서명된 페이로드는 암호화 서명(보통 HMAC)을 포함하며, 수신자가 공유 시크릿을 사용해 요청의 진위와 무결성을 검증할 수 있게 해줍니다.

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

일반적인 관행은 지수 백오프를 사용한 3~5회 재시도입니다. 그 이후에는 이벤트를 데드 레터 큐로 이동해 수동으로 검사하세요.

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

아니요, HTTPS는 도청과 변조로부터 페이로드와 서명을 보호하는 데 필수입니다. 항상 TLS를 사용하세요.

웹훅 페이로드를 테스트할 준비가 되셨나요? JSON formatter를 사용해 JSON 페이로드를 빠르게 정렬하고 검증해 보세요.