웹훅 받고 서명 검증하기
웹훅을 쓰면 새 입금이 저장되는 순간 82bank 가 여러분의 서버로 알려 줍니다. 몇 분마다 API 를 부르며 기다릴 필요가 없습니다. 다만 웹훅 주소는 누구나 알게 되면 호출할 수 있으므로, 받은 요청이 정말 82bank 에서 온 것인지 확인해야 합니다. 이 글은 그 확인, 곧 서명 검증과 함께 알아 둘 재시도 규칙을 설명합니다.
무엇이 오나
관리 화면 [데이터전송]에서 웹훅을 등록할 때 받을 이벤트를 고릅니다. 새 입금 transaction.deposit, 새 출금 transaction.withdrawal, 주문 매칭 order.matched, 매칭 해제 order.unmatched, 계좌 수집이 실패해 멈췄을 때의 account.error 다섯 가지입니다. 일이 생기면 다음과 같은 요청이 옵니다.
POST /hooks/82bank HTTP/1.1
Content-Type: application/json
User-Agent: 82bank-webhook/1
X-82bank-Event: transaction.deposit
X-82bank-Signature: 5f0c3a…(본문을 웹훅 시크릿으로 HMAC-SHA256 한 16진수 64자)
{
"id": "whd_…",
"event": "transaction.deposit",
"createdAt": "2026-11-18T03:12:41Z",
"data": {
"id": "tx_…", "accountId": "acc_…", "bankCode": "SH", "accountAlias": "운영 계좌",
"date": "2026-11-18", "time": "12:10:05", "type": "deposit",
"amount": 32000, "balance": 1286000,
"description": "타행이체", "counterparty": "홍길동", "memo": "",
"matchStatus": "matched", "orderNo": "A20261118-0012"
}
}
X-82bank-Event 에는 이벤트 이름이, X-82bank-Signature 에는 서명이 들어 있습니다. 서명은 요청 본문을 웹훅 시크릿(등록할 때 만들어진 값)으로 HMAC-SHA256 계산해 소문자 16진수로 쓴 것입니다. 시크릿을 아는 쪽은 82bank 와 여러분뿐이니, 같은 값을 계산할 수 있으면 82bank 가 보낸 것이고 본문도 바뀌지 않았다는 뜻입니다.
Node.js 로 검증하기
// Node.js + Express — 서명은 "받은 그대로의 본문"으로 계산해야 하므로 raw 로 받는다
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.BANK82_WEBHOOK_SECRET;
app.post("/hooks/82bank", express.raw({ type: "application/json" }), (req, res) => {
const got = req.get("X-82bank-Signature") || "";
const want = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
const same = got.length === want.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
if (!same) return res.status(401).end();
const evt = JSON.parse(req.body.toString("utf8"));
// evt.id 로 이미 처리한 알림인지 먼저 확인한다 (재시도로 같은 알림이 다시 올 수 있다)
console.log(evt.event, evt.data);
res.status(200).end(); // 10초 안에 2xx 로 답한다. 오래 걸리는 일은 답한 뒤에.
});
app.listen(3000);
핵심은 두 가지입니다. 첫째, 서명은 받은 바이트 그대로로 계산합니다. Express 의 express.json() 처럼 본문을 먼저 객체로 바꾸는 미들웨어를 거치면, 다시 문자열로 만들 때 공백이나 키 순서가 달라져 서명이 맞지 않습니다. 그래서 이 경로만 express.raw() 로 받습니다. 둘째, 비교는 timingSafeEqual 처럼 걸리는 시간이 내용과 상관없는 함수로 합니다. 보통의 문자열 비교는 앞에서부터 다른 글자를 만나면 바로 멈추기 때문에, 응답 시간을 재서 서명을 한 글자씩 맞혀 보는 공격에 쓰일 수 있습니다.
Python 으로 검증하기
# Python + Flask
import hmac, hashlib, os
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["BANK82_WEBHOOK_SECRET"].encode()
@app.post("/hooks/82bank")
def hook():
body = request.get_data() # 받은 그대로의 바이트
want = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
got = request.headers.get("X-82bank-Signature", "")
if not hmac.compare_digest(got, want):
abort(401)
evt = request.get_json()
print(evt["event"], evt["data"])
return "", 200
Flask 에서는 request.get_data() 가 받은 바이트를 그대로 돌려주고, hmac.compare_digest 가 시간 차이 없는 비교를 해 줍니다.
재시도와 중복
받는 서버는 10초 안에 2xx 로 답해야 합니다. 시간이 넘거나 2xx 가 아니면 82bank 는 그 알림을 대기열에 남기고 1분, 5분, 30분, 2시간, 12시간 뒤를 다음 시도 시각으로 잡습니다. 재시도는 5분마다 도는 작업이 처리하므로 실제로는 그 시각 뒤 5분 안에 갑니다. 3xx 리다이렉트는 따라가지 않고 실패로 봅니다. 처음까지 합쳐 6번 모두 실패하면 멈추고, 실패로 끝난 전송은 관리 화면의 전송 기록에서 [다시 보내기]로 직접 보낼 수 있습니다. 한 번 수집에서 바로 보내는 전송은 20건까지이고 나머지는 다음 5분 주기에 갑니다. 받는 쪽이 느리거나 꺼져 있어도 82bank 의 수집과 매칭은 멈추지 않습니다.
재시도가 있으니 같은 알림이 두 번 올 수 있습니다. 예를 들어 여러분의 서버가 일을 끝냈지만 답을 보내기 전에 연결이 끊기면, 82bank 는 실패로 보고 다시 보냅니다. 본문의 id 를 저장해 두고 이미 처리한 id 면 아무것도 하지 않고 200 을 주세요. 시간이 오래 걸리는 일(메일 보내기, 다른 API 호출)은 먼저 200 으로 답한 뒤 따로 처리하는 편이 안전합니다.
자주 하는 실수
- 웹훅 시크릿 대신 API 시크릿(
sk_…)으로 계산한다. 둘은 다른 값입니다. 상점 콜백은 또 다른 값인 상점 콜백 시크릿을 씁니다. - 본문을 JSON 으로 파싱한 뒤
JSON.stringify로 다시 만들어 계산한다. - 서명이 틀린 요청에 200 을 준다. 401 을 주고 내용은 쓰지 마세요.
- 웹훅만 믿고 놓친 거래를 다시 확인하지 않는다. 서버가 오래 꺼져 있었다면
GET /v1/accounts/{id}/transactions로 그 기간을 다시 받아 id 로 빠진 것을 채우세요.
주소는 https:// 만 등록할 수 있고, IP 주소, localhost 나 .internal 같은 내부 이름, 점이 없는 이름은 받지 않습니다. 계좌를 등록할 때 가져오는 지난 30일 치는 웹훅으로 보내지 않고, 등록한 날 이후의 새 거래만 처음 저장될 때 한 번 보냅니다. 개발 중에는 [시험 전송] 버튼으로 서명 검증 코드부터 확인해 보세요.