Redis Streams + HMAC + 202 패턴 — 실전 Webhook 시스템 설계 완전 가이드

오늘 다룰 내용
1. Redis Streams — CLI로 직접 확인하는 메시지 큐 동작 원리
2. HMAC-SHA256 — Webhook 진위 검증의 표준 방법
3. 202 Accepted 패턴 — Webhook Server가 타임아웃 나지 않는 이유

// 전체 흐름
블록체인 노드
  ↓ (WebSocket 이벤트)
ChainEventListener — 이벤트 수신
  ↓ (HMAC 서명 생성 후 발송)
Redis Streams — 메시지 내구성 보장
  ↓ (컨슈머 그룹 처리)
WebhookServer — 202 즉시 응답 + 백그라운드 처리
  ↓ (HMAC 서명 검증)
Core Banking / 원장 시스템

# 1. 스트림에 메시지 추가 (블록체인 이벤트 시뮬레이션)
$ redis-cli XADD blockchain:events *
  event_type NFTMinted
  tx_hash 0xabc123def456
  token_id 42
  recipient 0x1234…abcd
→ “1714348800123-0”  # 타임스탬프-시퀀스 형태의 고유 ID

# 2. 컨슈머 그룹 생성
$ redis-cli XGROUP CREATE blockchain:events webhook-workers $ MKSTREAM
→ OK

# 3. 컨슈머가 메시지 읽기 (ACK 전까지 PEL에 보관됨)
$ redis-cli XREADGROUP GROUP webhook-workers worker-1 COUNT 1 BLOCK 0 STREAMS blockchain:events >

# 4. 처리 완료 후 ACK
$ redis-cli XACK blockchain:events webhook-workers 1714348800123-0
→ (integer) 1

# 5. 미처리(ACK 안된) 메시지 목록 조회
$ redis-cli XPENDING blockchain:events webhook-workers – + 10

// Redis Streams 컨슈머 그룹 처리 패턴
async function consumeEvents() {
  // 신규 메시지 읽기 (‘>’ = 아직 미전달 메시지)
  const messages = await redis.xReadGroup(
    ‘webhook-workers’, ‘worker-1’,
    { key: ‘blockchain:events’, id: ‘>’ },
    { count: 10, block: 5000 }
  );

  for (const msg of messages) {
    await processEvent(msg);
    // 처리 완료 후 반드시 ACK
    await redis.xAck(‘blockchain:events’, ‘webhook-workers’, msg.id);
  }
}

# 방법 1: openssl 사용 (가장 범용적)
$ echo -n ‘{”event”:”NFTMinted”,”tokenId”:42}’ |
  openssl dgst -sha256 -hmac “your-secret-key”
→ SHA2-256(stdin)= a3f2c1d9e5b8…

# 방법 2: Python으로 생성
$ python3 -c “
import hmac, hashlib, json
payload = json.dumps({’event’:’NFTMinted’,’tokenId’:42}, separators=(‘,’,’:’))
sig = hmac.new(b’your-secret-key’, payload.encode(), hashlib.sha256).hexdigest()
print(f’X-Signature: sha256={sig}’)
“
→ X-Signature: sha256=a3f2c1d9e5b8…

# 방법 3: Node.js / TypeScript
$ node -e “
const {createHmac} = require(‘crypto’);
const payload = JSON.stringify({event:’NFTMinted’,tokenId:42});
const sig = createHmac(‘sha256′,’your-secret-key’).update(payload).digest(‘hex’);
console.log(‘X-Signature: sha256=’+sig);
”

import { createHmac, timingSafeEqual } from ‘crypto’;

function verifyWebhookSignature(
  rawBody: Buffer,
  signatureHeader: string,
  secret: string
): boolean {
  // 헤더 형식: “sha256=abcdef123456…”
  const [algo, receivedSig] = signatureHeader.split(‘=’);
  if (algo !== ‘sha256’) return false;

  // 서버 측에서 서명 재계산
  const expectedSig = createHmac(‘sha256’, secret)
    .update(rawBody)
    .digest(‘hex’);

  // timingSafeEqual: 타이밍 공격 방지 (중요!)
  return timingSafeEqual(
    Buffer.from(expectedSig, ‘hex’),
    Buffer.from(receivedSig, ‘hex’)
  );
}

timingSafeEqual이 중요한 이유

일반 문자열 비교(===)는 첫 글자가 틀리면 즉시 반환한다. 공격자는 응답 시간 차이로 서명의 앞 몇 글자를 유추할 수 있다(타이밍 공격). timingSafeEqual은 항상 전체 길이를 비교해 시간이 일정하다. 금융 시스템에서는 반드시 사용해야 한다.

잘못된 Webhook Server 패턴

// ✅ 올바른 Webhook Server — 202 패턴
app.post(‘/webhook’, async (req, res) => {
  // 1. 서명 검증 (빠름, ~1ms)
  const sig = req.headers[‘x-signature’] as string;
  if (!verifyWebhookSignature(req.rawBody, sig, SECRET)) {
    return res.status(401).json({ error: ‘Invalid signature’ });
  }

  // 2. Redis Streams에 즉시 저장 (빠름, ~2ms)
  await redis.xAdd(‘webhook:queue’, ‘*’, {
    payload: JSON.stringify(req.body),
    receivedAt: Date.now().toString()
  });

  // 3. 즉시 202 반환 (총 소요 ~5ms)
  res.status(202).json({ accepted: true });
  // 실제 처리는 별도 워커가 Redis Streams에서 소비
});

// Worker에서 멱등성 체크
async function processWebhookMessage(msg: StreamMessage) {
  const payload = JSON.parse(msg.payload);
  const idempotencyKey = `webhook:done:${payload.txHash}:`;

  // Redis SET NX — “없을 때만 세팅” (원자적 체크)
  const isNew = await redis.set(idempotencyKey, ‘1’, {
    NX: true, EX: 86400 // 24시간 후 만료
  });

  if (!isNew) {
    console.log(‘이미 처리된 이벤트, 스킵’);
    return; // 중복 처리 방지
  }

  // 실제 처리 (Core Banking, 원장, 알림)
  await updateCoreBanking(payload);
  await updateLedger(payload);
}

블록체인 이벤트
   ↓ WebSocket
ChainEventListener
   ↓ HMAC 서명 생성 후 HTTP POST
Webhook Server (POST /webhook)
   ├─ HMAC-SHA256 서명 검증 (~1ms)
   ├─ Redis XADD → webhook:queue (~2ms)
   └─ 202 Accepted 즉시 반환 (~1ms)
Webhook Worker (XREADGROUP)
   ├─ 멱등성 키 체크 (Redis SET NX)
   ├─ Core Banking 업데이트
   ├─ 원장 기록
   └─ XACK → 처리 완료 표시

오늘의 핵심 요약

• Redis Streams: XREADGROUP + XACK + PEL — 메시지는 ACK 전까지 사라지지 않는다
• HMAC-SHA256: rawBody 서명 + timingSafeEqual 비교 — 위조/변조를 원천 차단한다
• 202 패턴: 수신 즉시 응답 + 비동기 처리 — 타임아웃과 재시도 폭풍을 막는다

세 패턴은 독립적이지 않다. 조합해야 금융 수준 신뢰성이 나온다.