TryQuickToolBox

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

Backend2026-11-07TryQuickToolBox

타사 서비스로부터 이벤트를 수신하기 위한 웹훅 엔드포인트를 방금 구축했습니다. 테스트에서는 모든 것이 잘 작동하지만, 프로덕션에서는 일부 이벤트가 도착하지 않거나, 더 심하게는 중복 이벤트를 받아 데이터 불일치가 발생하는 것을 발견합니다. 이는 페이로드 진위성과 전달 신뢰성이라는 두 가지 중요한 측면에서 비롯되는 전형적인 웹훅 함정입니다.

웹훅은 이벤트에 의해 트리거되어 애플리케이션에 실시간으로 데이터를 푸시하는 HTTP 콜백입니다. 폴링과 달리 효율적이고 거의 즉각적입니다. 하지만 웹훅은 도전 과제를 안고 있습니다: 요청이 실제로 예상 발신자로부터 온 것인지 어떻게 알 수 있으며, 수신자가 일시적으로 다운되었을 때 실패를 어떻게 처리할 수 있을까요? 이 글에서는 서명된 페이로드와 재시도 메커니즘을 자세히 살펴보고, 탄력적인 웹훅 통합을 구축하기 위한 실용적인 패턴을 제공합니다.

웹훅에 서명이 필요한 이유

웹훅 엔드포인트는 공개적으로 접근 가능한 URL입니다. 검증 없이는 누구나 엔드포인트로 위조된 요청을 보내 무단 작업이나 데이터 손상을 유발할 수 있습니다. 서명된 페이로드는 각 요청에 암호화 서명을 추가하여 발신자의 신원을 확인하고 페이로드가 변조되지 않았음을 보장함으로써 이 문제를 해결합니다.

대부분의 제공업체는 공유 비밀을 사용하는 HMAC(해시 기반 메시지 인증 코드)을 사용합니다. 발신자는 비밀을 사용하여 페이로드의 해시를 계산하고 이를 헤더에 포함시킵니다. 수신 측에서 해시를 다시 계산하여 비교합니다. 일치하면 요청이 합법적인 것입니다.

HMAC 검증 구현

Node.js에서 일반적인 구현을 살펴보겠습니다. 제공업체가 X-Signature 헤더에 서명을 보내고, 이는 귀하의 비밀을 사용하여 원시 요청 본문의 HMAC-SHA256으로 계산된다고 가정합니다.

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

// Use raw body parser to preserve exact payload
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (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');
  }
  
  // Process the event
  const event = JSON.parse(req.body);
  // ... handle event
  
  res.status(200).send('OK');
});

핵심 사항:

재시도 전략 설계

서명이 있어도 네트워크 문제, 서버 다운타임 또는 시간 초과로 인해 전달이 실패할 수 있습니다. 강력한 재시도 전략은 시스템이나 발신자에 과부하를 주지 않으면서 최종 전달을 보장합니다.

1. 빠르게 확인하고 비동기적으로 처리

웹훅 엔드포인트는 가능한 한 빨리, 이상적으로는 몇 초 이내에 2xx 상태로 응답해야 합니다. 처리가 더 오래 걸리면 이벤트를 백그라운드 처리를 위해 큐에 넣으세요. 이렇게 하면 시간 초과를 방지하고 발신자가 전달을 성공으로 간주할 수 있습니다.

2. 지터를 포함한 지수 백오프 구현

전달이 실패하면(2xx가 아닌 응답 또는 시간 초과), 발신자는 지연을 늘려가며 재시도해야 합니다. 지수 백오프(예: 1초, 2초, 4초, 8초...)는 엔드포인트에 과도한 요청을 방지합니다. 무작위 지터를 추가하면 많은 웹훅이 동시에 실패할 때 발생하는 썬더링 허드 문제를 피할 수 있습니다.

재시도 일정 예시:

최대 재시도 횟수(예: 5회) 후에는 발신자가 중단하고 귀하에게 알려야 합니다(예: 이메일 또는 대시보드를 통해).

3. 멱등성으로 중복 처리

재시도는 중복 전달을 초래할 수 있습니다. 엔드포인트는 멱등성을 가져야 합니다: 동일한 이벤트를 여러 번 처리해도 한 번 처리한 것과 같은 효과를 가져야 합니다. 페이로드에서 고유한 이벤트 ID를 사용하여 저장하세요. 처리하기 전에 해당 ID가 이미 확인되었는지 확인하고, 그렇다면 재처리 없이 200을 반환하세요.

일반적인 접근 방식:

비교: 서명된 페이로드 vs. 기타 보안 조치

방법 장점 단점
HMAC 서명 진위성과 무결성 검증; 상태 비저장 공유 비밀 관리 필요
IP 허용 목록 구현 간단 IP 변경 가능; 동적 환경에 부적합
기본 인증 추가 용이 모든 요청에 자격 증명 전송; 보안 취약
헤더의 JWT 클레임 및 만료 포함 가능 토큰 발급/검증 오버헤드

HMAC 서명은 상태 비저장, 효율적이며 올바르게 구현될 때 강력한 보안을 제공하기 때문에 사실상 표준입니다.

웹훅 소비자를 위한 모범 사례

웹훅 생산자를 위한 모범 사례

웹훅 구현 테스트

ngrok과 같은 도구를 사용하여 로컬 서버를 노출하고 웹훅 전달을 시뮬레이션하세요. 서명 검증 및 멱등성 로직에 대한 단위 테스트를 작성하세요. 부하 테스트의 경우 대규모로 서명된 요청을 보낼 수 있는 도구를 고려하세요.

디버깅할 때 원시 페이로드와 헤더를 검사하세요. JSON 포맷터는 페이로드 구조를 시각화하는 데 도움이 됩니다. 웹훅 페이로드를 빠르게 예쁘게 인쇄하고 유효성 검사하려면 JSON Formatter를 사용해 보세요.

FAQ

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

서명된 페이로드에는 수신자가 발신자의 신원을 확인하고 페이로드가 변경되지 않았음을 보장할 수 있는 암호화 서명(일반적으로 HMAC)이 포함됩니다. 공유 비밀과 요청 본문을 사용하여 계산됩니다.

웹훅은 몇 번 재시도해야 하나요?

보편적인 숫자는 없지만, 일반적인 관행은 지수 백오프를 사용하여 3~5회 재시도하는 것입니다. 그 후에는 이벤트가 실패한 것으로 간주되며 소비자에게 조사하거나 수동으로 재생하도록 알려야 합니다.

웹훅 서명에 HMAC 대신 JWT를 사용할 수 있나요?

예, JWT를 사용할 수 있지만 복잡성(토큰 발급, 만료)이 추가됩니다. HMAC은 더 간단하며 대부분의 사용 사례에 충분합니다. 기존 인프라와 요구 사항에 따라 선택하세요.

웹훅 페이로드를 검사하고 디버깅할 준비가 되셨나요? 무료 JSON Formatter를 사용하여 JSON을 즉시 포맷하고 유효성을 검사하세요.