웹훅 Payload 명세

Commerce API에서 전송하는 모든 웹훅 타입과 페이로드 구조입니다.

총 25개의 웹훅 타입을 지원합니다.

ℹ️

웹훅 수신 시 주의사항

idempotency_key 를 사용하여 중복 처리를 방지하세요
웹훅 수신 후 200 응답을 즉시 반환하고, 비즈니스 로직은 비동기로 처리하세요
웹훅 URL은 HTTPS만 지원됩니다

Webhook

웹훅 타입 선택

카테고리와 웹훅 타입을 선택하세요.

카테고리

웹훅 타입

상세

구독 승인

subscription.approved

설명

구독 신청이 승인되어 정식으로 구독이 시작될 때 전송됩니다. 자동승인 또는 관리자 승인 후 발송됩니다.

발송 시점

관리자 승인 또는 자동 승인 시

타입 코드

101

공통

공통 필드 (최상위)

▼

모든 웹훅에 공통으로 포함되는 최상위 필드입니다.

필드명

타입

필수

설명

webhook_type

string

웹훅 이벤트 타입 (예: subscription.approved, order.done)

project_key

string

프로젝트 고유 키

idempotency_key

string

멱등성 키 (중복 처리 방지용 UUID)

payload

object

이벤트 상세 데이터

주문

주문 기본 정보

▼

payload 객체 내의 주문 기본 필드입니다.

필드명

타입

필수

설명

order_number

string

주문 번호

order_name

string

주문명

order_request_type

string

주문 요청 타입 (subscription_requested)

status

string

주문 상태 (subscription_request_completed)

type

string

주문 타입 (shop)

price

number

결제 금액

tax_free_price

number

면세 금액

cancelled_price

number

취소된 금액

cancelled_tax_free_price

number

취소된 면세 금액

reserved_cancel_price

number

예약된 취소 금액

reserved_cancel_tax_free_price

number

예약된 취소 면세 금액

unit

string

통화 단위 (KRW)

created_at

string

주문 생성 일시 (ISO 8601)

purchased_at

string

결제 완료 일시 (ISO 8601)

구독 정보

▼

구독 계약 및 청구 관련 필드입니다.

필드명

타입

필수

설명

order_subscriptions

array

구독 계약 목록

order_subscription_id

string

구독 계약 고유 ID

order_number

string

구독 주문 번호

order_name

string

구독 주문명

status

string

구독 상태 (subscribing, paused, terminated 등)

approval_status

string

승인 상태 (approval_approved_auto, approval_approved 등)

approval_at

string

승인 일시

service_start_at

string

서비스 시작일

service_end_at

string

서비스 종료일

current_duration

number

현재 회차

created_last_duration

number

생성된 마지막 회차

payment_last_duration

number

결제된 마지막 회차

total_subscription_duration

number

총 구독 회차

total_subscription_label

string

회차 표시명 (예: 24회차)

subscription_payment_cycle_type

string

결제 주기 (1month, 3month 등)

subscription_payment_date

number

결제일

subscription_type

string

구독 타입 (regular_subscription)

is_first_prepaid

boolean

선결제 여부

price

number

회차별 결제 금액

origin_price

number

원래 금액

tax_free_price

number

비과세 금액

setup_price

number

초기 설치비

quantity

number

구독 수량

use_delivery

boolean

배송 사용 여부

delivery_type

string

배송 타입 (parcel 등)

delivery_cycle_type

number

배송 주기 타입

amount_delivery_base_fee

number

기본 배송비

amount_delivery_area_cost

number

산간 추가 배송비

amount_delivery_discount

number

배송비 할인액

membership_type

string

회원 유형 (personal, business)

user_id

string

사용자 ID

has_pending_request

boolean

대기 중인 요청 여부

pause_count

number

일시정지 횟수

pause_total_days

number

총 일시정지 일수

order_subscription_adjustments

array

회차별 가격 조정 목록

order_subscription_adjustment_id

string

가격 조정 ID

duration

number

적용 회차

name

string

조정 항목명

type

string

조정 타입 (setup_price, discount)

price

number

조정 금액 (할인은 음수)

tax_free_price

number

조정 면세 금액

created_at

string

생성 일시

options

array

선택된 옵션 목록

product_id

string

상품 ID

product_option_snapshot_id

string

옵션 스냅샷 ID

type

string

옵션 타입 (selectable_options 등)

status

string

옵션 상태

price

number

옵션 가격

tax_free_price

number

옵션 면세 금액

keys

array

옵션 키 배열 (예: ["색상", "사이즈"])

name

array

옵션 값 배열 (예: ["화이트", "L"])

products

array

구독 상품 목록

product_id

string

상품 ID

product_snapshot_id

string

상품 스냅샷 ID

name

string

상품명

desc

string

상품 설명

type

string

상품 타입

display_price

number

표시 가격

discount_price

number

할인 금액

discount_price_type

string

할인 타입 (percentage, fixed_price)

tax_free_price

number

면세 금액

images

array

상품 이미지 URL 배열

use_subscription

boolean

구독 사용 여부

상품

상품 정보

▼

주문에 포함된 상품 정보입니다.

필드명

타입

필수

설명

products

array

주문 상품 목록

product_id

string

상품 ID

name

string

상품명

price

number

상품 가격

origin_price

number

원래 가격

quantity

number

수량

total_price

number

총 가격

total_subscription_duration

number

총 구독 회차

product

object

상품 상세 정보

결제

결제 영수증 정보

▼

결제 성공 시 영수증 상세 정보입니다.

필드명

타입

필수

설명

receipt_status

string

영수증 상태 (receipt_billing_key_published 등)

사용자

사용자 정보

▼

구매자 정보입니다.

필드명

타입

필수

설명

username

string

구매자 이름

user_email

string

구매자 이메일

user_phone

string

구매자 전화번호

user_business_number

string

사업자등록번호 (B2B)

user_company_name

string

회사명 (B2B)

user

object

구매자 상세 정보

user_id

string

사용자 고유 ID

name

string

사용자 이름

email

string

이메일

phone

string

전화번호

membership_type

string

회원 유형 (member, guest)

status

string

회원 상태 (active, inactive)

✅구독 승인

subscription.approved