리셀러 웹훅

하위 판매자의 PG 신청 단계가 바뀌거나 MID 연결이 끝나면, 부트페이가 리셀러가 등록한 주소로 서명된 POST 를 보낸다. 결제 완료를 알리는 가맹점 웹훅 과는 다른 통로이고 모양·서명도 다르다.

핵심 요약

• 받을 주소와 이벤트는 PUT /v2/reseller/webhook 으로 등록한다. 서명 비밀(secret)은 처음 설정할 때와 교체할 때 한 번만 응답에 나온다.
• 모든 요청에 X-Bootpay-Signature 가 붙는다. 받은 본문 그대로(파싱하기 전 바이트)로 서명을 다시 계산해 맞는지 본다.
• 처리했으면 HTTP 200 과 {"success": true} 로 답한다. 그 밖의 응답·시간 초과는 다시 보낸다(최대 10번).
• 같은 이벤트가 두 번 올 수 있고 순서가 뒤바뀔 수 있다 → X-Bootpay-Event-Id 로 중복을 거르고, 최신 상태는 등록 상태 조회 로 맞춘다.

설정 — 받을 주소 등록

{
  "url":        "https://reseller.example.com/bootpay/webhook",
  "events":     ["seller.onboarding.changed", "seller.activated"],
  "secret_set": true,
  "updated_at": "2026-10-27T15:00:00+09:00",
  "secret":     "whsec_example_secret"
}json

설정 조회는 GET https://api.bootpay.co.kr/v2/reseller/webhook — 같은 모양에서 secret 만 빠진다.

이벤트

판매자가 부트페이 콘솔에서 직접 낸 신청이라도 그 가맹점이 리셀러 하위이면 상태 변경 웹훅이 온다.

받는 요청

POST /bootpay/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Bootpay-Webhook/1.0
X-Bootpay-Event: seller.onboarding.changed
X-Bootpay-Event-Id: evt_0f3c9a1b2d4e5f60718293a4
X-Bootpay-Signature: t=1793080800,v1=5d1c...(64자 hex)

{"id":"evt_0f3c9a1b2d4e5f60718293a4","event":"seller.onboarding.changed","created_at":"2026-10-27T15:00:00+09:00","data":{"provider_id":"65a1c0aa8f1b5b00367a0001","onboarding_id":"6718a0aa8f1b5b00367a0101","kind":"pg_join","status":1,"status_name":"구비서류 전달 필요","stage":"doc_wait","stage_owner":"merchant","due_at":"2026-10-30T18:00:00+09:00","reject_reason":null}}

서명 검증

X-Bootpay-Signature: t=<unix 초>,v1=<hex> 의 v1 은 HMAC-SHA256(서명 비밀, "<t>.<받은 본문>") 의 hex 값이다.

1. 헤더에서 t 와 v1 을 꺼낸다.
2. 받은 본문 바이트 그대로​(JSON 파싱·재직렬화하지 않은 원문)로 "<t>.<본문>" 을 만든다.
3. 보관한 서명 비밀로 HMAC-SHA256 을 계산해 v1 과 시간 일정 비교로 맞춘다.
4. t 가 지금보다 5분 넘게 지났으면 버리기를 권한다(재전송 공격 방지).

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.BOOTPAY_RESELLER_WEBHOOK_SECRET

// 서명은 원문 바이트로 계산한다 — express.json() 보다 앞에서 raw 로 받는다
app.post('/bootpay/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const header = req.get('X-Bootpay-Signature') || ''
    const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
    const expected = crypto.createHmac('sha256', SECRET).update(`${parts.t}.${req.body}`).digest('hex')
    const valid = parts.v1 && expected.length === parts.v1.length &&
        crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
    if (!valid || Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return res.status(400).end()

    const event = JSON.parse(req.body)
    // event.id 로 이미 처리한 이벤트인지 먼저 확인한다
    res.json({ success: true })
})javascript

import hashlib, hmac, json, os, time
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ['BOOTPAY_RESELLER_WEBHOOK_SECRET'].encode()

@app.post('/bootpay/webhook')
def bootpay_webhook():
    raw = request.get_data()  # 파싱 전 원문 바이트
    parts = dict(p.split('=', 1) for p in request.headers.get('X-Bootpay-Signature', '').split(',') if '=' in p)
    expected = hmac.new(SECRET, f"{parts.get('t', '')}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get('v1', '')) or abs(time.time() - int(parts.get('t', 0))) > 300:
        return '', 400

    event = json.loads(raw)
    # event['id'] 로 이미 처리한 이벤트인지 먼저 확인한다
    return jsonify(success=True)python

재시도

다시 보낼 때도 id·본문은 처음과 같다. 서명(t·v1)은 보낼 때마다 새로 계산한다. 시간이 오래 걸리는 처리는 먼저 200 으로 답하고 뒤에서 한다.

에러 코드 (설정 API)