웹훅 서명 검증 구현하기: HMAC-SHA256, 5분 타임스탬프, eventId 중복 거르기
KAT Cloud 웹훅은 X-Webhook-Signature 헤더에 HMAC-SHA256 서명을 담아 보냅니다. 원본 본문으로 서명을 계산하고, 5분 넘은 타임스탬프를 거절하고, 최대 3번 오는 재전송을 eventId로 거르는 방법을 Node.js와 Python 코드로 정리했습니다.

KAT Cloud 웹훅이 정말 KAT Cloud에서 왔는지 확인하려면, 받은 본문 원문 앞에 X-Webhook-Timestamp 값과 점(.)을 붙인 문자열을 계정 비밀값으로 HMAC-SHA256 계산하고, v1=를 붙인 결과가 X-Webhook-Signature와 같은지 상수 시간으로 비교하면 됩니다. 타임스탬프가 지금과 5분 넘게 차이 나면 거절하고, 통과한 알림은 eventId로 이미 처리했는지 걸러야 합니다. 실패한 알림은 처음을 포함해 최대 3번 오기 때문입니다.
서명 헤더와 비밀값
모든 웹훅 요청에는 두 헤더가 붙습니다(서명 검증 문서).
| 헤더 | 값 |
|---|---|
X-Webhook-Timestamp | 보낸 시각(유닉스 초) |
X-Webhook-Signature | v1= + HMAC-SHA256(비밀값, "<timestamp>.<본문 원문>")의 16진수 |
비밀값은 whsec_ 뒤에 16진수 64자리가 붙은 문자열로, 계정에 하나이며 모든 이벤트와 웹훅 주소가 같은 값을 씁니다. GET /webhook/secret으로 조회하고(없으면 만들어 돌려줌), POST /webhook/secret/rotate로 재발급합니다. 키로 쓸 때는 whsec_까지 포함한 문자열 그대로 씁니다. 앞부분을 떼거나 16진수를 바이트로 바꾸면 서명이 맞지 않습니다. HMAC의 원리는 용어집 HMAC에 있습니다.
검증 순서 다섯 단계
- 1본문을 JSON으로 파싱하기 전에 받은 바이트 그대로 확보합니다. 파싱 후 다시 직렬화하면 공백과 키 순서가 바뀌어 서명이 달라집니다.
- 2타임스탬프가 지금 시각과 5분 넘게 차이 나면 거절합니다. 가로챈 요청을 나중에 다시 보내는 재전송 공격을 막습니다.
- 3
"<timestamp>.<본문 원문>"을 비밀값으로 HMAC-SHA256 계산하고 앞에v1=를 붙입니다. - 4헤더 값과 상수 시간 비교로 맞춰 보고, 다르면 401로 거절합니다.
- 5통과하면
eventId로 이미 처리한 알림인지 거른 뒤 처리합니다.
Node.js 예제
Express에서는 이 경로에만 express.raw()를 써서 본문을 Buffer로 받습니다. 아래 예제는 재발급 중에 새 값과 이전 값을 함께 받아 주는 처리까지 넣었습니다.
const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRETS = [process.env.KAT_WEBHOOK_SECRET, process.env.KAT_WEBHOOK_SECRET_OLD].filter(Boolean);
const TOLERANCE = 300; // 5분
function sign(secret, timestamp, rawBody) {
return 'v1=' + crypto.createHmac('sha256', secret)
.update(`${timestamp}.`).update(rawBody).digest('hex');
}
function isValid(rawBody, timestamp, signature) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || !signature) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - ts) > TOLERANCE) return false;
const got = Buffer.from(signature);
return SECRETS.some((secret) => {
const want = Buffer.from(sign(secret, timestamp, rawBody));
return want.length === got.length && crypto.timingSafeEqual(want, got);
});
}
app.post('/webhook/katcloud', express.raw({ type: 'application/json', limit: '5mb' }), async (req, res) => {
if (!isValid(req.body, req.get('X-Webhook-Timestamp'), req.get('X-Webhook-Signature'))) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
// 운영에서는 eventId를 고유 키로 둔 DB 테이블에 기록합니다
if (await db.processedEvents.exists(event.eventId)) return res.status(200).send('OK');
try {
await handleEvent(event);
await db.processedEvents.insert(event.eventId); // 처리 성공 뒤에만 완료 표시
res.status(200).send('OK');
} catch (err) {
console.error(err);
res.status(500).send('retry'); // 완료 표시가 없으니 재전송 때 다시 처리
}
});timingSafeEqual은 길이가 다르면 예외를 던지므로 길이를 먼저 비교합니다. CALL_COMPLETED는 받아쓰기가 길 수 있어 limit을 넉넉히 둡니다.
Python(FastAPI) 예제
import hashlib, hmac, json, os, time
from fastapi import FastAPI, Request, Response
app = FastAPI()
SECRETS = [s for s in (os.environ.get("KAT_WEBHOOK_SECRET"), os.environ.get("KAT_WEBHOOK_SECRET_OLD")) if s]
TOLERANCE = 300
def is_valid(raw: bytes, timestamp: str | None, signature: str | None) -> bool:
if not timestamp or not signature:
return False
try:
ts = int(timestamp)
except ValueError:
return False
if abs(time.time() - ts) > TOLERANCE:
return False
for secret in SECRETS:
digest = hmac.new(secret.encode(), timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
if hmac.compare_digest(("v1=" + digest).encode(), signature.encode()):
return True
return False
@app.post("/webhook/katcloud")
async def webhook(request: Request):
raw = await request.body() # request.json()이 아니라 원본 바이트
if not is_valid(raw, request.headers.get("X-Webhook-Timestamp"), request.headers.get("X-Webhook-Signature")):
return Response("invalid signature", status_code=401)
event = json.loads(raw)
if db_event_done(event["eventId"]):
return Response("OK")
try:
handle_event(event)
mark_event_done(event["eventId"])
return Response("OK")
except Exception:
return Response("retry", status_code=500)Flask를 쓴다면 request.get_data()로 원본을 받으면 됩니다. Flask 기반 서버 골격은 Python으로 웹훅 서버 만들기를 참고하세요.
재전송과 중복 거르기 규칙
전송·다시 보내기 문서 기준으로, 받는 서버가 2xx가 아닌 코드로 답하거나 10초 안에 답하지 않으면 실패로 보고 다시 보냅니다. 처음을 포함해 최대 3번이고, 첫 실패 약 5초 뒤, 그다음 약 15초 뒤입니다. 다시 보내도 eventId는 같습니다.
- 처리에 성공한 알림만 완료로 표시합니다. 실패한 알림까지 완료로 표시하면 재전송이 와도 버려집니다.
- 응답이 늦어 실패로 처리된 알림도 다시 올 수 있습니다. 오래 걸리는 작업은 영속 큐에 넣은 뒤 바로 2xx로 답하세요.
- 메모리의 Set은 재시작이나 서버 여러 대에서 중복을 막지 못합니다. 운영에서는
eventId를 고유 키로 둔 DB를 씁니다.
비밀값을 재발급할 때
재발급하면 바로 다음 알림부터, 다시 보내는 알림까지 새 값으로 서명합니다. 받는 서버에 새 값을 넣기 전에 온 알림은 검증에 실패하고, 재전송(약 20초)이 끝나면 더는 오지 않습니다. 그래서 위 예제처럼 반영하는 동안에는 새 값과 이전 값 중 하나로 맞으면 통과시키고, 반영이 끝나면 이전 값을 지웁니다. 비밀값이 새어 나갔다면 바로 재발급하세요. 검증 코드를 맞춰 볼 때는 POST /webhook/{webhookId}/test가 실제와 같은 비밀값으로 서명한 테스트 알림("isTest": true)을 보내 줍니다. 테스트 결과 읽는 법은 웹훅 등록·테스트에 있습니다.
KAT Cloud 가입하기로 7일 무료 체험을 시작하거나, 연동 구조가 복잡하다면 도입 상담을 신청하세요.
자주 묻는 질문
서명이 계속 맞지 않습니다. 무엇부터 확인하나요?
KAT Cloud 웹훅 서명이 맞지 않는 가장 흔한 원인은 JSON으로 파싱한 뒤 다시 직렬화한 본문으로 계산하는 경우입니다. 받은 바이트 그대로 계산하는지, 비밀값을 whsec_까지 포함한 문자열 그대로 키로 쓰는지, 계산 문자열이 "타임스탬프.본문" 순서인지 차례로 확인하세요.
서버 시계가 틀리면 검증에 실패하나요?
KAT Cloud 웹훅 검증 절차는 X-Webhook-Timestamp가 지금 시각과 5분 넘게 차이 나면 거절하도록 안내합니다. 받는 서버의 시계가 크게 틀리면 정상 알림도 거절되므로 NTP로 시간을 맞춰 두세요.
같은 알림이 두 번 오는 이유는 무엇인가요?
KAT Cloud는 받는 서버가 2xx로 답하지 않거나 10초 안에 응답하지 않으면 처음을 포함해 최대 3번까지 같은 알림을 다시 보냅니다. 다시 보낸 알림의 eventId는 같으므로, eventId로 이미 처리한 알림을 걸러야 합니다.
- #웹훅
- #서명 검증
- #HMAC
- #보안
- #Node.js
- #Python



