웹훅 처리 가이드

주문 웹훅 설정에서 URL 등록과 기본 코드를 확인해요. 이 문서는 설정 이후​, 각 이벤트를 받았을 때 실제로 무엇을 해야 하는지​​에 집중해요.

결제 웹훅

상태별 처리 (status)

결제 웹훅의 status는 숫자​​예요 (커머스 API 의 주문 status 와 다른 값 체계).

결제 웹훅 처리 코드

app.post('/webhook/bootpay', async (req, res) => {
    const { receipt_id, status, price, order_id } = req.body

    // 1. 결제 조회 API로 검증 (위변조 방지)
    const receipt = await Bootpay.getReceipt(receipt_id)

    if (receipt.status !== status || receipt.price !== price) {
        return res.status(200).json({ success: true })
    }

    // 2. 상태별 처리
    switch (status) {
        case 1: // 결제 완료
            await db.orders.update({
                bootpay_receipt_id: receipt_id,
                amount: price,
                method: receipt.method,
                status: 'paid',
                paid_at: new Date()
            }, { where: { order_id } })

            // 재고 차감
            const order = await db.orders.findOne({ where: { order_id } })
            for (const item of order.items) {
                await db.products.decrement('stock', {
                    by: item.quantity, where: { id: item.product_id }
                })
            }
            break

        case 20: // 결제 취소
            await db.orders.update(
                { status: 'refunded' },
                { where: { bootpay_receipt_id: receipt_id } }
            )
            // 재고 복구
            const refundOrder = await db.orders.findOne({
                where: { bootpay_receipt_id: receipt_id }
            })
            for (const item of refundOrder.items) {
                await db.products.increment('stock', {
                    by: item.quantity, where: { id: item.product_id }
                })
            }
            break

        case 2: // 가상계좌 발급 (입금 대기)
            await db.orders.update(
                { status: 'pending', bootpay_receipt_id: receipt_id },
                { where: { order_id } }
            )
            break
    }

    res.status(200).json({ success: true })
})javascript

커머스 웹훅

이벤트별 가맹점 액션

주문 이벤트

구독 이벤트

Bootpay 내부 이벤트 매핑 참조

웹훅 이벤트명은 Bootpay 내부 WebhookType 상수에서 변환돼요. 디버깅이나 로그 분석 시 참고해요.

주문 이벤트 (내부 상수 — 응답 필드가 아니에요)

구독 이벤트 (내부 상수 — 응답 필드가 아니에요)

커머스 웹훅 코드 패턴

패턴 1: 200 먼저, 처리는 비동기

웹훅은 30초 이내 응답해야 해요. 비즈니스 로직은 비동기로 처리해요.

app.post('/webhooks/bootpay', async (req, res) => {
    const { idempotency_key, webhook_type: event } = req.body
    // 구형(봉투 없는) 본문도 함께 받아요
    const data = req.body.payload ?? req.body

    // 1. 중복 체크
    const exists = await db.webhookLogs.findOne({ where: { idempotency_key } })
    if (exists) return res.status(200).json({ success: true })

    // 2. 웹훅 로그 저장
    await db.webhookLogs.create({ idempotency_key, event, data: JSON.stringify(data), status: 'received' })

    // 3. 즉시 200 반환
    res.status(200).json({ success: true })

    // 4. 비동기로 처리
    processWebhook(event, data, idempotency_key).catch(err => {
        console.error('웹훅 처리 실패:', err)
    })
})

async function processWebhook(event, data, key) {
    switch (event) {
        case 'order.done': await handleOrderDone(data); break
        case 'order.cancelled': await handleOrderCancelled(data); break
        case 'subscription.approved': await handleSubscriptionApproved(data); break
        case 'subscription.renewed': await handleSubscriptionRenewed(data); break
        case 'subscription.terminated':
        case 'subscription.admin_terminated':
            await handleSubscriptionTerminated(data); break
        case 'order.partial_cancelled':
            await handleOrderPartialCancelled(data); break
        case 'subscription.hold_on':
            await handleSubscriptionHoldOn(data); break
    }
    await db.webhookLogs.update({ status: 'processed' }, { where: { idempotency_key: key } })
}javascript

@app.route('/webhooks/bootpay', methods=['POST'])
def webhook():
    body = request.get_json()
    idempotency_key = body.get('idempotency_key')
    event = body['webhook_type']
    # 구형(봉투 없는) 본문도 함께 받아요
    data = body.get('payload', body)

    if WebhookLog.query.filter_by(idempotency_key=idempotency_key).first():
        return jsonify({'success': True}), 200

    WebhookLog.create(idempotency_key=idempotency_key, event=event, status='received')
    thread = threading.Thread(target=process_webhook, args=(event, data, idempotency_key))
    thread.start()

    return jsonify({'success': True}), 200python

<?php
Route::post('/webhooks/bootpay', function (Request $request) {
    $payload = $request->all();
    $idempotencyKey = $payload['idempotency_key'] ?? null;
    // 구형(봉투 없는) 본문도 함께 받아요
    $data = $payload['payload'] ?? $payload;

    if (WebhookLog::where('idempotency_key', $idempotencyKey)->exists()) {
        return response()->json(['success' => true]);
    }

    WebhookLog::create([
        'idempotency_key' => $idempotencyKey,
        'event' => $payload['webhook_type'],
        'status' => 'received'
    ]);

    ProcessWebhookJob::dispatch($payload['webhook_type'], $data, $idempotencyKey);
    return response()->json(['success' => true]);
});php

패턴 2: 이벤트별 처리 함수

// order.done — 주문 결제 완료
async function handleOrderDone(data) {
    const { order_number, price } = data   // payload 에 order_id 는 없어요 — order_number 로 맞춰요
    await db.orders.update(
        { status: 'paid', paid_at: new Date() },
        { where: { bootpay_order_number: order_number } }
    )
    // 재고 차감
    const order = await db.orders.findOne({ where: { bootpay_order_number: order_number } })
    for (const item of order.items) {
        await db.products.decrement('stock', { by: item.quantity, where: { id: item.product_id } })
    }
    await sendEmail(order.user_id, 'order_confirmed', { order_number, price })
}

// order.cancelled — 주문 취소
async function handleOrderCancelled(data) {
    const { order_number } = data
    await db.orders.update({ status: 'cancelled' }, { where: { bootpay_order_number: order_number } })
    const order = await db.orders.findOne({ where: { bootpay_order_number: order_number } })
    for (const item of order.items) {
        await db.products.increment('stock', { by: item.quantity, where: { id: item.product_id } })
    }
}

// subscription.approved — 구독 승인
// 신청 결제와 함께 승인되면 주문 모양(order_subscriptions[]), 관리자 승인이면 구독 모양(order_subscription_id)으로 와요
async function handleSubscriptionApproved(data) {
    const ids = data.order_subscription_id
        ? [data.order_subscription_id]
        : (data.order_subscriptions ?? []).map(s => s.order_subscription_id)
    await db.subscriptions.update(
        { service_active: true, status: 'active' },
        { where: { bootpay_subscription_id: ids } }
    )
}

// subscription.terminated — 구독 해지
async function handleSubscriptionTerminated(data) {
    await db.subscriptions.update(
        { service_active: false, status: 'terminated' },
        { where: { bootpay_subscription_id: data.order_subscription_id } }
    )
}

// subscription.renewed — 구독 갱신 (회차 결제 성공)
async function handleSubscriptionRenewed(data) {
    await db.subscriptions.update(
        { current_period_end: new Date(data.payment_next_at), status: 'active', service_active: true },
        { where: { bootpay_subscription_id: data.order_subscription_id } }
    )
}javascript

구독 해지 복구 (restore)

subscription.restored 는 가맹점이 복구를 알 수 있는 유일한 통로​​예요. 해지 웹훅(terminated·admin_terminated)을 받고 이미 서비스를 껐을 텐데, 복구는 부트페이 관리자에서 처리되고 가맹점이 부를 수 있는 API 가 없어요.

이 이벤트에만 payload.restore 블록이 함께 실려요.

// subscription.restored — 관리자 해지 복구
async function handleSubscriptionRestored(data) {
    const r = data.restore ?? {}
    await db.subscriptions.update(
        {
            service_active: true,
            status: 'active',
            current_period_end: r.next_payment_at ? new Date(r.next_payment_at) : undefined
        },
        { where: { bootpay_order_number: data.order_number } }
    )
    // 해지 기간 동안 건너뛴 회차가 있으면 정산·이용권 계산에 반영해요
    if (r.skipped_cycles > 0) {
        await reconcileSkippedCycles(data.order_number, r.skipped_cycles, r.charge_missed_bills)
    }
}javascript

패턴 3: 환불 이벤트 처리 (전체/부분)

order.cancelled와 order.partial_cancelled는 처리 로직이 달라요.

// order.cancelled — 전체 취소/환불
async function handleOrderCancelled(data) {
    const { order_number } = data
    await db.orders.update({ status: 'refunded' }, { where: { bootpay_order_number: order_number } })
    // 전체 재고 복구
}

// order.partial_cancelled — 부분 취소/환불
async function handleOrderPartialCancelled(data) {
    // 지금은 payload 가 비어 와요(알려진 문제) — 주문 상세를 다시 조회해 같은 값을 읽어요
    const { order_number, price, cancelled_price } = data
    await db.orders.update(
        { total_amount: price - cancelled_price, status: 'partially_refunded' },
        { where: { bootpay_order_number: order_number } }
    )
    // 부분 취소된 상품만 재고 복구
}javascript

웹훅 DB 테이블 (멱등성 보장)

웹훅 로그 테이블을 만들어 idempotency_key 기반으로 중복을 방지해요.

CREATE TABLE webhook_logs (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    idempotency_key VARCHAR(100) NOT NULL UNIQUE,
    event           VARCHAR(50) NOT NULL,
    data            TEXT,
    status          VARCHAR(20) DEFAULT 'received',  -- received → processed → failed
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_key (idempotency_key),
    INDEX idx_event (event)
);sql

디버깅: 웹훅이 안 올 때

로컬 개발 시 웹훅 받기

로컬 개발 환경에서는 외부에서 접근할 수 없으므로 터널링 도구를 사용해요.

# ngrok 사용
ngrok http 3000
# → https://abc123.ngrok.io 주소를 웹훅 URL로 등록

# 또는 localtunnel
npx localtunnel --port 3000bash