커머스 웹훅 설정

하위 프로젝트에 연결된 부트페이 커머스 프로젝트가 주문·구독 웹훅을 보낼 주소와 받을 이벤트를 리셀러가 정한다. 판매자가 커머스 관리자 화면(개발 연동 설정)에서 정하는 웹훅과 같은 설정​​이다. PG 신청 단계를 알려 주는 리셀러 웹훅 과는 다른 통로다.

핵심 요약

• PUT 은 주소(url)와 이벤트(events)를 한 번에 바꾼다. url 은 꼭 보낸다 — 빈 문자열("")이면 웹훅을 끈다. 키를 빼면 400 이다(실수로 꺼지지 않게).
• events 를 비우면 모든 주문·구독 이벤트를 받는다(지금 판매자 설정과 같은 기본값). 고르면 고른 이벤트만 보낸다.
• 주소는 500자 이하의 https:// 주소만 받는다. 이름을 풀어 나온 IP 가 내부·사설·부트페이 서버 주소면 거부한다.
• 주소는 새로 만들어지는 주문·구독부터 쓰인다(주문·구독이 만들어질 때 주소를 복사해 둔다). 받을 이벤트는 보낼 때마다 지금 설정을 본다.
• 재시도 횟수와 본문 형식(Content-Type)은 그 커머스 프로젝트의 지금 값을 그대로 쓴다(기본 10번 · application/x-www-form-urlencoded). 바꾸려면 커머스 관리자 화면에서 바꾼다.
• 커머스 프로젝트가 아직 없으면 404 다. 커머스 연동 재시도 로 먼저 만든다.

API 정보

설정 조회는 GET https://api.bootpay.co.kr/v2/reseller/seller/app/commerce/:app_id/webhook — 요청 본문 없이 같은 모양으로 응답한다.

요청 파라미터

코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const appId = '65a1c0ab8f1b5b00367a0002'
const res = await fetch(`https://api.bootpay.co.kr/v2/reseller/seller/app/commerce/${appId}/webhook`, {
    method: 'PUT',
    headers: {
        'Authorization': RESELLER_AUTH,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        url: 'https://reseller.example.com/bootpay/commerce-webhook',
        events: ['order.done', 'order.cancelled', 'subscription.approved']
    })
})
console.log(await res.json())javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

app_id = '65a1c0ab8f1b5b00367a0002'
res = requests.put(
    f'https://api.bootpay.co.kr/v2/reseller/seller/app/commerce/{app_id}/webhook',
    headers={'Authorization': auth},
    json={
        'url': 'https://reseller.example.com/bootpay/commerce-webhook',
        'events': ['order.done', 'order.cancelled', 'subscription.approved']
    }
)
print(res.json())python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)
APP_ID='65a1c0ab8f1b5b00367a0002'

curl -X PUT "https://api.bootpay.co.kr/v2/reseller/seller/app/commerce/$APP_ID/webhook" \
  -H "Authorization: Basic $RESELLER_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://reseller.example.com/bootpay/commerce-webhook","events":["order.done","order.cancelled","subscription.approved"]}'bash

응답

{
  "app_id":       "65a1c0ab8f1b5b00367a0002",
  "project_id":   "65a1c0ab8f1b5b00367a0006",
  "url":          "https://reseller.example.com/bootpay/commerce-webhook",
  "events":       ["order.done", "order.cancelled", "subscription.approved"],
  "retry_count":  10,
  "content_type": "application/x-www-form-urlencoded"
}json

응답 파라미터

이벤트

본문의 webhook_type 으로 어떤 이벤트인지 안다. 결제완료·취소·부분취소 중 일부 경로는 본문에 옛 표기(ORDER_COMPLETED · ORDER_CANCELLED · ORDER_PARTIAL_CANCELLED)로 오는데, 고를 때는 아래 이름(order.done · order.cancelled · order.partial_cancelled)을 쓴다.

알림톡 발송 결과(alimtalk.*)와 입금 확인(deposit.*)은 각자 설정이 따로 있어 여기서 고를 수 없다.

받는 요청

• 커머스 프로젝트 설정의 형식(content_type)으로 POST 한다. 서명 헤더는 없다 — 받은 주문·구독은 커머스 API 로 다시 조회해 확인한다.
• 처리했으면 응답 본문에 {"success": true} 를 담는다. 없거나 false 이면 retry_count 만큼 다시 보낸다.
• 같은 이벤트가 두 번 올 수 있다. 본문의 idempotency_key 나 주문·구독 id 로 중복을 거른다.

에러 코드