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

Backend2026-11-11TryQuickToolBox

결제 통합을 배포하고 스테이징에서는 모든 것이 잘 작동합니다. 그런데 프로덕션에서 고객이 결제를 하면 엔드포인트가 2초 동안 타임아웃되고 주문은 활성화되지 않습니다. 한편 결제 제공업체는 동일한 이벤트를 세 번 재시도하고, 앱은 성공한 주문 하나에 대해 중복 주문 세 개를 생성합니다. 웹훅은 단순한 HTTP POST처럼 보이지만 어려운 부분은 신뢰와 전달 보장입니다.

이 글에서는 웹훅 통합을 가장 자주 망가뜨리는 두 가지, 즉 요청이 정말 발신자로부터 온 것인지 검증하는 방법과 부작용을 중복시키지 않고 재시도를 처리하는 방법을 다룹니다.

웹훅이란 무엇인가

웹훅은 역방향 API 호출입니다. 서버가 매분 제공업체에 "새로운 거 있나요?"라고 폴링하는 대신, 이벤트가 발생하면 제공업체가 등록한 URL로 HTTP 요청을 푸시합니다. 페이로드는 보통 JSON이고, 이벤트 유형은 본문이나 헤더에 있습니다.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

발신자 측에서 중요한 설계 결정 두 가지가 있으며, 어떤 제공업체를 평가할 때 둘 다 확인해야 합니다. 페이로드에 서명하는가, 실패 시 재시도하는가?

서명 없는 웹훅이 위험한 이유

웹훅 URL은 공개되어 있습니다. URL을 알게 된 누구나 가짜 payment.succeeded 이벤트를 POST하여 결제되지 않은 주문을 결제된 것으로 표시할 수 있습니다. IP 허용 목록은 조금 도움이 되지만, 제공업체는 IP를 변경하고 CDN 뒤에서 실행되며 안정적인 목록을 얻지 못할 수 있습니다.

강력한 해결책은 여러분과 제공업체만 아는 공유 비밀을 사용하여 원시 요청 본문에 대한 HMAC 서명을 생성하는 것입니다. 제공업체가 서명을 계산해 헤더로 보내면, 여러분이 다시 계산해 비교합니다.

서명을 올바르게 검증하는 방법

세 가지 세부 사항을 틀리기 쉽습니다:

// Node.js / Express 예제
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // 오래된 요청 거부 (재전송 공격 방지)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... 이벤트 처리
  res.status(200).send('ok');
});

express.raw() 미들웨어에 주목하세요. 이 라우트 앞에 express.json()을 마운트하면 본문이 이미 파싱되어 서명 검사가 조용히 실패합니다. 매우 흔한 버그입니다.

이벤트를 잃지 않는 재시도 설계

웹훅 전달은 정확히 한 번이 아니라 최소 한 번입니다. 네트워크가 실패하고, 배포 중 컨테이너가 재시작되며, 제공업체는 여러분의 200 응답이 진짜인지 알 수 없습니다. 그래서 제공업체는 종종 몇 시간 또는 며칠 동안 지수 백오프로 재시도합니다.

빠르게 응답하고 나중에 처리하세요

엔드포인트는 최소한의 작업만 해야 합니다: 검증, 원시 이벤트 저장, 2xx 반환. 이메일 발송, 다른 API 호출, 인보이스 생성 같은 무거운 작업은 백그라운드 작업에서 처리해야 합니다. 처리가 제공업체의 타임아웃보다 오래 걸리면, 작업을 완료했더라도 요청이 실패로 간주되어 재시도됩니다.

  1. 서명과 타임스탬프를 검증합니다.
  2. 이벤트 ID에 고유 제약 조건이 있는 테이블에 이벤트를 삽입합니다.
  3. 즉시 200을 반환합니다.
  4. 저장된 이벤트를 비동기적으로 처리하고 완료로 표시합니다.

멱등성: 중복에 대한 진짜 해결책

재시도가 발생하기 때문에 핸들러는 두 번 실행해도 안전해야 합니다. 이벤트 ID가 자연스러운 멱등성 키입니다.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

삽입이 0개의 행에 영향을 주면 이 이벤트를 전에 본 것입니다. 확인 응답하고 넘어가세요. 비즈니스 로직에도 같은 아이디어를 적용하세요: 결제 활성화 시 주문 ID를 고유 키로 사용하여 두 번째 이벤트가 두 번째 활성화를 생성하지 못하게 합니다.

의도적으로 상태 코드 선택하기

상태제공업체 동작사용 시기
200 / 204전달됨으로 표시이벤트 수락됨 (이미 처리된 경우에도)
400보통 재시도 안 함절대 처리할 수 없는 잘못된 페이로드
401보통 재시도 안 함서명 불일치 — 비밀을 확인하세요
429백오프와 함께 재시도속도 제한 중
500 / 503백오프와 함께 재시도일시적 실패, DB 다운, 배포 진행 중

저장할 수 없는 이벤트에 200을 반환하는 것은 최악의 선택입니다. 제공업체가 재시도를 중단하고 이벤트는 영원히 사라집니다. 5xx를 반환하고 재시도가 제 역할을 하게 하세요.

프로덕션을 위한 실용 체크리스트

로컬에서 웹훅 테스트하기

localhost에서 공개 POST를 쉽게 받을 수 없습니다. 옵션: 개발 포트를 노출하는 터널링 도구, 제공업체에 CLI가 있다면 그것, 또는 서명된 페이로드를 핸들러로 보내 검증 경로를 테스트하는 작은 스크립트입니다.

가장 가치 있는 테스트는 중복입니다: 동일한 이벤트를 두 번 보내고 시스템이 동일한 상태로 끝나는지 확인하세요. 그런 다음 오래된 타임스탬프가 있는 이벤트를 보내 거부되는지 확인하세요. 그런 다음 본문의 한 바이트를 변조하고 서명 검사가 실패하는지 확인하세요.

페이로드 디버깅

웹훅 본문은 JSON이고, 잘못되었거나 깊게 중첩된 페이로드는 로그에서 읽기 어렵습니다. 파싱 코드를 작성하기 전에 포맷터가 구조를 빠르게 검사하는 데 도움이 됩니다. JSON 포맷터는 브라우저에서 실행되므로 고객 데이터를 서버로 보내지 않고 캡처한 페이로드를 붙여넣을 수 있습니다.

FAQ

웹훅과 API의 차이점은 무엇인가요?

API는 풀 기반입니다: 데이터가 필요할 때 코드가 제공업체를 호출합니다. 웹훅은 푸시 기반입니다: 이벤트가 발생하면 제공업체가 엔드포인트를 호출합니다. 대부분의 통합은 둘 다 사용합니다 — 이벤트 알림에는 웹훅을, 전체 세부 정보를 가져오거나 작업을 수행하려면 API를 사용합니다.

HMAC 서명이 항상 일치하지 않는 이유는 무엇인가요?

흔한 원인은 원시 바이트 대신 다시 직렬화된 본문에 서명하는 것입니다. 공백, 키 순서, 유니코드 이스케이프가 모두 해시를 변경합니다. JSON 미들웨어 전에 원시 요청 본문을 읽고, 비밀과 해시 알고리즘이 제공업체 문서와 일치하는지 확인하세요.

웹훅 재시도가 보장되나요?

아니요. 제공업체는 일반적으로 지수 백오프로 제한된 기간 동안 재시도한 후 포기합니다. 웹훅을 진실의 원천이 아닌 빠른 알림 채널로 취급하세요: 제공업체의 API와 주기적으로 조정하여 누락된 이벤트가 결국 수정되도록 하세요.

오늘 웹훅 수신기를 구축하거나 디버깅하고 있다면 서명 검증과 멱등성 저장을 확실히 하는 것부터 시작하세요. 이 두 가지 변경만으로 실제 웹훅 사고의 대부분을 제거할 수 있습니다.