웹훅 받고 서명 검증하기

2026. 11. 18. · 82bank

웹훅을 쓰면 새 입금이 저장되는 순간 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 으로 답한 뒤 따로 처리하는 편이 안전합니다.

자주 하는 실수

주소는 https:// 만 등록할 수 있고, IP 주소, localhost 나 .internal 같은 내부 이름, 점이 없는 이름은 받지 않습니다. 계좌를 등록할 때 가져오는 지난 30일 치는 웹훅으로 보내지 않고, 등록한 날 이후의 새 거래만 처음 저장될 때 한 번 보냅니다. 개발 중에는 [시험 전송] 버튼으로 서명 검증 코드부터 확인해 보세요.

다른 글