본문 바로가기
Q&A2026년 5월 30일2분 읽기

토스페이먼츠 v2 webhook signature 검증 — Node.js에서 일부 요청만 실패

양
양미래
조회 353댓글 4

토스페이먼츠 v2 webhook을 Node.js Express로 수신 중인데 5% 정도 요청에서 signature 검증이 실패합니다.

app.post('/webhooks/toss', express.json(), (req, res) => {
  const signature = req.headers['x-tosspayments-signature']
  const body = JSON.stringify(req.body)
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(body)
    .digest('base64')
  if (signature !== expected) {
    return res.status(401).send('Invalid signature')
  }
  // 처리
})

증상

  • 대부분 요청 검증 OK
  • 약 5% (특히 한글 메모 포함 요청) 검증 실패
  • 실패한 요청을 토스 콘솔에서 재시도하면 또 실패

UTF-8 인코딩 문제일까요? 어떻게 처리하시나요?

댓글 4

김김영삼5개월 전

가장 흔한 함정입니다. express.json()이 body를 파싱한 후 JSON.stringify로 다시 만든 문자열이 원본과 일치하지 않습니다.


토스가 보내는 원본 body가 정확히 다음과 같다고 가정:


{"orderId":"X","amount":1000,"memo":"커피 한 잔"}

express.json()이 받아서 JS 객체로 파싱 → 다시 JSON.stringify하면:


{"orderId":"X","amount":1000,"memo":"커피 한 잔"}
// 또는 (Node 버전·환경에 따라)
{"orderId":"X","amount":1000,"memo":"\uCEE4\uD53C \uD55C \uC794"}

한글이 \u escape로 변환되면 byte 시퀀스 달라져서 signature 다르게 계산됩니다.


해결 — raw body 보존


// express.raw로 받기
app.post('/webhooks/toss',
express.raw({ type: 'application/json' }),
(req, res) => {
const rawBody = req.body // Buffer
const signature = req.headers['x-tosspayments-signature']
const expected = crypto
.createHmac('sha256', SECRET)
.update(rawBody) // Buffer 그대로
.digest('base64')

if (signature !== expected) {
return res.status(401).send('Invalid')
}

// 검증 후 파싱
const data = JSON.parse(rawBody.toString('utf-8'))
// 처리
}
)

또는 express.json with verify


app.post('/webhooks/toss',
express.json({
verify: (req, res, buf) => {
req.rawBody = buf // 원본 buffer 보존
}
}),
(req, res) => {
const signature = req.headers['x-tosspayments-signature']
const expected = crypto.createHmac('sha256', SECRET)
.update(req.rawBody) // 보존된 원본
.digest('base64')
// ...
}
)

Next.js API route라면


// app/api/webhooks/toss/route.ts
export async function POST(req: Request) {
const rawBody = await req.text() // raw string
const signature = req.headers.get('x-tosspayments-signature')

const expected = crypto.createHmac('sha256', SECRET)
.update(rawBody, 'utf-8')
.digest('base64')

if (signature !== expected) {
return Response.json({ error: 'Invalid' }, { status: 401 })
}

const data = JSON.parse(rawBody)
// ...
}

5%가 한글 메모 포함된 거 맞으면 위 패턴으로 해결될 겁니다.

풀풀스택지훈5개월 전

저는 토스페이먼츠 + KG이니시스 둘 다 운영하는데 각자 webhook signature 알고리즘이 미세하게 달라요. SDK 직접 작성하지 마시고 가능하면 토스페이먼츠 공식 SDK의 webhook helper 쓰세요.

재재훈(guest)5개월 전
"실패한 요청을 토스 콘솔에서 재시도하면 또 실패"가 키 포인트입니다. 토스가 보낸 원본 그대로 다시 보내는데 검증 실패면 코드 측 문제 확정. raw body 보존 패턴이 정답.
자자바스크립트러(guest)5개월 전
제가 운영하는 서비스에도 비슷한 케이스가 있어서 try해볼 만하네요. 결과 나오면 share할게요.
Ctrl+Enter로 등록