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

Backend2026-11-15TryQuickToolBox

프로덕션에서 웹훅이 실패하는 이유

웹훅 엔드포인트를 구축하고 로컬에서 테스트했을 때는 모든 것이 잘 작동합니다. 하지만 프로덕션에서는: 제공자가 중복 이벤트를 보내거나, 엔드포인트가 시간 초과되거나, 공격자가 요청을 위조할 수 있습니다. 갑자기 통합이 불안정하고 안전하지 않게 됩니다.

웹훅은 개념적으로 간단합니다—이벤트에 의해 트리거되는 HTTP 콜백—하지만 프로덕션 수준의 구현은 보안과 안정성을 신중하게 처리해야 합니다. 이 가이드에서는 두 가지 중요한 측면을 다룹니다: 진위 여부를 확인하는 서명된 페이로드와 실패를 처리하는 재시도 전략입니다.

웹훅이란 무엇인가?

웹훅은 사용자 정의 HTTP 콜백입니다. 소스 시스템(예: 결제 성공)에서 이벤트가 발생하면, 이벤트에 대한 데이터를 포함하여 사용자가 제공한 URL로 HTTP POST 요청을 보냅니다. 이 푸시 모델은 폴링보다 효율적입니다.

그러나 웹훅은 다음과 같은 과제를 제시합니다:

먼저 보안을 해결해 보겠습니다.

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

서명된 페이로드는 공유 비밀을 사용하여 요청 본문의 암호화 서명을 생성합니다. 발신자는 이 서명을 헤더(예: X-Signature)에 포함합니다. 엔드포인트는 서명을 다시 계산하고 비교합니다. 일치하면 요청이 진본입니다.

HMAC 서명 작동 방식

대부분의 제공자는 HMAC-SHA256을 사용합니다. 서명은 공유 비밀을 사용하여 원시 요청 본문에 대해 계산됩니다. 흐름은 다음과 같습니다:

  1. 제공자와 소비자가 비밀 키를 공유합니다.
  2. 제공자가 페이로드를 생성하고 HMAC-SHA256(secret, payload)을 계산한 후 헤더에 담아 보냅니다.
  3. 소비자가 요청을 받아 원시 본문을 읽고 동일한 HMAC을 계산하여 비교합니다.

중요: 받은 그대로의 원시 본문을 사용하세요—JSON을 파싱하고 다시 직렬화하면 바이트가 변경되어 서명이 깨질 수 있습니다.

서명 검증 구현하기

Express를 사용한 Node.js 예제입니다:

const crypto = require('crypto');
const express = require('express');
const app = express();

// 웹훅 경로에는 원시 본문 파서 사용
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // 이벤트 처리
  const event = JSON.parse(req.body);
  // ... 이벤트 처리
  
  res.status(200).send('OK');
});

타이밍 공격을 방지하려면 항상 crypto.timingSafeEqual과 같은 상수 시간 비교를 사용하세요.

기타 보안 고려 사항

안정적인 재시도 구현하기

보안 엔드포인트가 있더라도 네트워크 문제나 일시적인 실패로 인해 웹훅 전달이 실패할 수 있습니다. 강력한 재시도 메커니즘은 이벤트가 손실되지 않도록 보장합니다.

발신자 측 재시도 전략

웹훅 발신자를 구축하는 경우 지터를 사용한 지수 백오프를 구현하세요. 예를 들어:

썬더링 허드 문제를 피하기 위해 무작위 지터를 추가하세요. 최대 시도 횟수 후 중지하고 알림을 보내세요.

수신자 측 모범 사례

웹훅 소비자로서 발신자의 재시도 정책을 제어할 수는 없지만 엔드포인트를 탄력적으로 만들 수 있습니다:

멱등성으로 중복 처리하기

웹훅 제공자는 종종 시간 초과 시 재시도하므로 동일한 이벤트를 여러 번 받을 수 있습니다. 처리를 멱등하게 만드세요:

데이터베이스 고유 인덱스를 사용한 예제:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // 고유 제약 위반
      return; // 이미 처리됨
    }
    throw err;
  }
  // 이벤트 처리
}

비교: 웹훅 보안 접근 방식

접근 방식 장점 단점
HMAC 서명 강력한 무결성, 널리 지원됨 비밀 관리 필요
기본 인증 간단함 덜 안전함, 헤더에 자격 증명 포함
IP 허용 목록 구현하기 쉬움 IP가 변경될 수 있음, 견고하지 않음

HMAC 서명은 웹훅 보안의 사실상 표준입니다.

로컬에서 웹훅 테스트하기

ngrok 또는 localtunnel과 같은 도구는 로컬 서버를 인터넷에 노출하여 테스트할 수 있게 해줍니다. 항상 시뮬레이션된 실패로 서명 검증 및 재시도 로직을 테스트하세요.

웹훅의 JSON 페이로드를 검사할 때 포맷팅하면 디버깅에 도움이 됩니다. JSON Formatter를 사용하여 웹훅 페이로드를 예쁘게 출력하고 유효성을 검사해 보세요.

FAQ

웹훅 서명을 어떻게 검증합니까?

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

웹훅 엔드포인트가 다운되면 어떻게 해야 합니까?

대부분의 제공자는 지수 백오프로 재시도합니다. 엔드포인트가 빠르게 2xx를 반환하고 비동기적으로 처리하여 다운타임 영향을 최소화하세요.

서명 없이 웹훅을 사용할 수 있습니까?

위험합니다. 서명이 없으면 공격자가 요청을 위조할 수 있습니다. 항상 서명된 페이로드를 사용하거나 최소한 HTTPS를 통한 기본 인증을 사용하세요.

결론

웹훅은 강력하지만 보안과 안정성에 주의가 필요합니다. 진위 여부를 확인하기 위해 HMAC 서명 검증을 구현하고, 재시도와 중복을 우아하게 처리하도록 시스템을 설계하세요. 이러한 관행을 통해 웹훅 통합은 견고하고 프로덕션 준비가 완료됩니다.