Webhook

스토어의 상태 변경을 등록한 HTTPS 주소에 JSON POST로 전달합니다. 수신 서버는 원문 서명을 검증하고, 중복 이벤트를 안전하게 처리해야 합니다.

수신 주소 등록

1.
HTTPS 수신 서버 준비
외부에서 접근할 수 있는 HTTPS 주소를 준비합니다. 운영 환경에서는 HTTP·localhost·사설/예약 IP·내부 도메인·URL 사용자 정보를 허용하지 않습니다.
2.
이벤트 및 필터 설정
스토어 대시보드 → 연동·개발자 → Webhook에서 수신 주소와 구독 이벤트를 등록합니다. 필요 시 필터, 사용자 지정 헤더와 전달 필드를 설정합니다.
3.
서명 키 보관 및 테스트
생성·교체 시 한 번 표시되는 signingSecret을 서버에 저장합니다. webhook.test로 서명 검증, 중복 처리, 내부 큐 저장과 2xx 응답을 확인합니다.

스토어당 활성 수신 주소는 최대 20개입니다. 서명 키를 분실했거나 유출이 의심되면 교체합니다.

전달 규칙

항목	동작
전달 보장	At-least-once. 동일한 이벤트가 중복 도착할 수 있습니다.
업무 이벤트	업무 변경과 같은 DB 트랜잭션에 기록합니다. 구독 이벤트·필터가 일치하는 활성 수신 주소마다 전송 건을 생성합니다.
이벤트 ID	payload.id와 X-Quartz-Event-ID. 여러 수신 주소로 전달되어도 동일합니다.
Delivery ID	X-Quartz-Delivery. 수신 주소별 전송 건의 ID이며 재시도 중 유지됩니다.
서명 시각	X-Quartz-Timestamp는 Unix 초 단위입니다. 재시도마다 새로 생성되며 occurredAt과 구별합니다.
수신 응답	5초 안에 2xx를 반환하면 전송 완료로 처리합니다.

권장 수신 순서

원문 확보 → 시각·서명 검증 → Delivery ID 중복 확인 → 내부 큐 저장 → 2xx 응답 순서로 처리합니다. 중복 기록과 큐 저장은 원자적으로 처리하고, 실제 지급 작업은 큐에서 실행합니다.

이벤트 참조

이벤트별 전달 시점과 data 필드입니다. 금액은 정수 문자열로 전달합니다.

주문

전달 시점

주문 행이 처음 저장된 직후

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.created 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.created",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "paid",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": null,
    "exchangeCount": 0,
    "exchangedAt": null
  }
}

전달 시점

주문 상태가 paid로 변경된 직후

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.paid 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.paid",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "paid",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": null,
    "exchangeCount": 0,
    "exchangedAt": null
  }
}

전달 시점

API 또는 판매자 직접 입력 중 먼저 완료되는 지급을 기다릴 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.fulfillment_pending 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.fulfillment_pending",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "paid",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": null,
    "exchangeCount": 0,
    "exchangedAt": null
  }
}

API로 지급하기 전 orderId로 주문을 다시 조회해 status가 paid인지 확인하세요. 판매자 지급이나 구매자 환불이 먼저 끝난 주문에는 지급 요청이 거부됩니다.

전달 시점

구매자에게 지급할 내용이 확정되어 주문 상태가 fulfilled가 될 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.fulfilled 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.fulfilled",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "fulfilled",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": "2026-07-19T01:03:10.000Z",
    "exchangeCount": 0,
    "exchangedAt": null
  }
}

전달 시점

주문 상태가 rejected 또는 stock_shortage가 될 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.
`failureCode*`	`rejected \| stock_shortage`	지급 실패를 만든 주문 상태입니다.
`recoveryStatus*`	`manual_review_available`	스토어 관리자가 주문을 검토하거나 재시도할 수 있음을 나타냅니다.

store.order.failed 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.failed",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "stock_shortage",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": null,
    "exchangeCount": 0,
    "exchangedAt": null,
    "failureCode": "stock_shortage",
    "recoveryStatus": "manual_review_available"
  }
}

전달 시점

교환 지급 횟수가 이전 값보다 증가할 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.exchanged 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.exchanged",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "fulfilled",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": "2026-07-19T01:03:10.000Z",
    "exchangeCount": 1,
    "exchangedAt": "2026-07-20T04:30:00.000Z"
  }
}

전달 시점

기존 지급 전 환불 경로에서 상태 변경을 알릴 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	주문 ID입니다. 주문 재조회와 지급 멱등 키로 사용합니다.
`orderNumber*`	`string`	화면 표시용 주문 번호입니다. 현재 값은 # 뒤에 orderId가 붙습니다.
`status*`	`enum`	이벤트 발생 시점의 주문 상태입니다.
`buyer.userId*`	`12자리 숫자`	구매자의 Quartz 사용자 ID입니다.
`buyer.nicknameSnapshot*`	`string`	주문 당시 저장된 구매자 닉네임입니다.
`currency*`	`string`	금액 통화 코드입니다.
`subtotalAmount*`	`정수 문자열`	할인 전 상품 금액입니다.
`discountAmount*`	`정수 문자열`	주문에 적용된 총 할인액입니다.
`totalAmount*`	`정수 문자열`	실제 결제된 금액입니다.
`lineItems*`	`object[]`	주문 상품 스냅샷입니다. 현재 한 주문에는 한 상품 행이 들어갑니다.
`lineItems[].orderLineId*`	`12자리 숫자`	주문 상품 행 ID이며 현재 orderId와 같습니다.
`lineItems[].productId*`	`12자리 숫자`	구매한 상품 ID입니다.
`lineItems[].productNameSnapshot*`	`string`	구매 당시 상품명입니다.
`lineItems[].quantity*`	`integer`	지급해야 하는 수량입니다.
`lineItems[].unitPrice*`	`정수 문자열`	구매 당시 개당 금액입니다.
`lineItems[].lineTotal*`	`정수 문자열`	해당 상품 행의 최종 금액입니다.
`lineItems[].selectedOptions*`	`object[]`	선택한 옵션의 안정적인 ID와 표시명입니다. 구매자가 입력한 원문과 원가 정보는 제외됩니다.
`couponApplications*`	`object[]`	적용 쿠폰 목록입니다. 쿠폰이 없으면 빈 배열입니다.
`couponApplications[].couponId`	`12자리 숫자`	적용된 쿠폰 ID입니다.
`couponApplications[].scope`	`string`	쿠폰 적용 범위입니다.
`couponApplications[].discountAmount`	`정수 문자열`	쿠폰으로 할인된 금액입니다.
`couponApplications[].discountBps`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`paidAt`	`RFC 3339 \| null`	결제 완료 시각입니다. 아직 결제 전이면 null이거나 생략됩니다.
`fulfilledAt`	`RFC 3339 \| null`	지급 완료 시각입니다. 지급 전이면 null이거나 생략됩니다.
`exchangeCount*`	`integer`	이 주문의 교환 지급 횟수입니다.
`exchangedAt`	`RFC 3339 \| null`	가장 최근 교환 지급 시각입니다.

store.order.cancelled 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.cancelled",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "refunded",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ],
    "couponApplications": [],
    "paidAt": "2026-07-19T01:02:03.000Z",
    "fulfilledAt": null,
    "exchangeCount": 0,
    "exchangedAt": null
  }
}

기존 이벤트는 호환성을 위해 유지합니다. 새 수량별 환불은 store.order.refunded를 구독하세요.

전달 시점

수동·API·72시간 만료 처리로 주문의 환불 수량이 증가할 때

data 필드

필드	형식	설명
`orderId*`	`12자리 숫자`	환불된 주문 ID입니다.
`orderNumber*`	`string`	#과 주문 ID로 구성된 주문번호입니다.
`status*`	`paid \| fulfilled \| refunded`	환불 처리 후의 주문 상태입니다.
`currency*`	`KRW \| USD`	환불 통화입니다.
`quantity / amount*`	`integer / string`	이번에 환불 처리한 수량과 금액입니다.
`refundedQuantity / refundedAmount*`	`integer / string`	주문 전체의 누적 환불 수량과 금액입니다.

store.order.refunded 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.refunded",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "paid",
    "currency": "KRW",
    "quantity": 1,
    "amount": "12000",
    "refundedQuantity": 1,
    "refundedAmount": "12000"
  }
}

계좌이체 주문에서는 환불 접수 알림이며 실제 은행송금 완료를 뜻하지 않습니다. 수량별 상태는 /fulfillment에서 다시 확인하세요.

기존 충전 거래 (호환)

전달 시점

스토어 충전 요청이 처음 저장된 직후

data 필드

필드	형식	설명
`chargeId*`	`12자리 숫자`	스토어 충전 요청 ID입니다.
`chargeNumber*`	`string`	화면 표시용 충전 번호입니다.
`userId*`	`12자리 숫자`	충전을 요청한 사용자 ID입니다.
`amount*`	`정수 문자열`	사용자가 결제할 금액입니다.
`creditAmount*`	`정수 문자열`	승인 시 구매 잔액에 반영할 금액입니다.
`currency*`	`string`	통화 코드입니다.
`paymentMethod*`	`string`	계좌이체 계열 충전 수단입니다.
`status*`	`string`	이벤트 발생 후 충전 상태입니다.
`previousStatus`	`string \| null`	상태 변경 전 값입니다. 생성 이벤트에서는 null입니다.
`processedAt`	`RFC 3339 \| null`	승인·거절 등 처리가 확정된 시각입니다.

store.charge.created 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.charge.created",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "chargeId": "202607190010",
    "chargeNumber": "#202607190010",
    "userId": "202607190002",
    "amount": "50000",
    "creditAmount": "50000",
    "currency": "KRW",
    "paymentMethod": "bank_transfer",
    "status": "pending",
    "previousStatus": null,
    "processedAt": null
  }
}

전달 시점

충전 요청의 status가 이전 값과 달라진 직후

data 필드

필드	형식	설명
`chargeId*`	`12자리 숫자`	스토어 충전 요청 ID입니다.
`chargeNumber*`	`string`	화면 표시용 충전 번호입니다.
`userId*`	`12자리 숫자`	충전을 요청한 사용자 ID입니다.
`amount*`	`정수 문자열`	사용자가 결제할 금액입니다.
`creditAmount*`	`정수 문자열`	승인 시 구매 잔액에 반영할 금액입니다.
`currency*`	`string`	통화 코드입니다.
`paymentMethod*`	`string`	계좌이체 계열 충전 수단입니다.
`status*`	`string`	이벤트 발생 후 충전 상태입니다.
`previousStatus`	`string \| null`	상태 변경 전 값입니다. 생성 이벤트에서는 null입니다.
`processedAt`	`RFC 3339 \| null`	승인·거절 등 처리가 확정된 시각입니다.

store.charge.status_changed 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.charge.status_changed",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "chargeId": "202607190010",
    "chargeNumber": "#202607190010",
    "userId": "202607190002",
    "amount": "50000",
    "creditAmount": "50000",
    "currency": "KRW",
    "paymentMethod": "bank_transfer",
    "status": "approved",
    "previousStatus": "pending",
    "processedAt": "2026-07-19T01:05:00.000Z"
  }
}

후기

전달 시점

후기가 처음 저장된 직후

data 필드

필드	형식	설명
`reviewId*`	`12자리 숫자`	후기 ID입니다.
`productId*`	`12자리 숫자`	후기가 작성된 상품 ID입니다.
`orderId*`	`12자리 숫자`	후기 작성 권한의 기준이 된 주문 ID입니다.
`userId*`	`12자리 숫자`	후기 작성자 ID입니다.
`nicknameSnapshot*`	`string`	이벤트 생성 당시 작성자 닉네임입니다.
`rating*`	`integer`	1부터 5까지의 별점입니다.
`content`	`string`	후기 본문입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`images`	`string[]`	후기 이미지 목록입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`visible*`	`boolean`	스토어에 공개되는 후기인지 나타냅니다.
`hiddenAt`	`RFC 3339 \| null`	숨김 또는 삭제 처리 시각입니다.

store.review.created 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.review.created",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "reviewId": "202607190020",
    "productId": "202607190003",
    "orderId": "202607190001",
    "userId": "202607190002",
    "nicknameSnapshot": "구매자",
    "rating": 5,
    "visible": true
  }
}

전달 시점

별점·본문·이미지 또는 공개 상태가 변경된 직후

data 필드

필드	형식	설명
`reviewId*`	`12자리 숫자`	후기 ID입니다.
`productId*`	`12자리 숫자`	후기가 작성된 상품 ID입니다.
`orderId*`	`12자리 숫자`	후기 작성 권한의 기준이 된 주문 ID입니다.
`userId*`	`12자리 숫자`	후기 작성자 ID입니다.
`nicknameSnapshot*`	`string`	이벤트 생성 당시 작성자 닉네임입니다.
`rating*`	`integer`	1부터 5까지의 별점입니다.
`content`	`string`	후기 본문입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`images`	`string[]`	후기 이미지 목록입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`visible*`	`boolean`	스토어에 공개되는 후기인지 나타냅니다.
`hiddenAt`	`RFC 3339 \| null`	숨김 또는 삭제 처리 시각입니다.

store.review.updated 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.review.updated",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "reviewId": "202607190020",
    "productId": "202607190003",
    "orderId": "202607190001",
    "userId": "202607190002",
    "nicknameSnapshot": "구매자",
    "rating": 4,
    "visible": true
  }
}

전달 시점

후기가 숨김 또는 삭제 상태로 변경된 직후

data 필드

필드	형식	설명
`reviewId*`	`12자리 숫자`	후기 ID입니다.
`productId*`	`12자리 숫자`	후기가 작성된 상품 ID입니다.
`orderId*`	`12자리 숫자`	후기 작성 권한의 기준이 된 주문 ID입니다.
`userId*`	`12자리 숫자`	후기 작성자 ID입니다.
`nicknameSnapshot*`	`string`	이벤트 생성 당시 작성자 닉네임입니다.
`rating*`	`integer`	1부터 5까지의 별점입니다.
`content`	`string`	후기 본문입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`images`	`string[]`	후기 이미지 목록입니다. 기본 anonymizeFields 설정에서는 전달되지 않습니다.
`visible*`	`boolean`	스토어에 공개되는 후기인지 나타냅니다.
`hiddenAt`	`RFC 3339 \| null`	숨김 또는 삭제 처리 시각입니다.

store.review.hidden 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.review.hidden",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "reviewId": "202607190020",
    "productId": "202607190003",
    "orderId": "202607190001",
    "userId": "202607190002",
    "nicknameSnapshot": "구매자",
    "rating": 4,
    "visible": false,
    "hiddenAt": "2026-07-20T03:00:00.000Z"
  }
}

쿠폰과 재고

전달 시점

스토어 쿠폰이 처음 저장된 직후

data 필드

필드	형식	설명
`couponId*`	`12자리 숫자`	생성된 쿠폰 ID입니다.
`name*`	`string`	쿠폰 관리 이름입니다.
`discountType*`	`amount \| percent`	정액 또는 정률 할인 방식입니다.
`discountAmount*`	`정수 문자열`	정액 할인 금액입니다.
`discountBps*`	`integer`	정률 할인값입니다. 1,000은 10%입니다.
`status*`	`active \| disabled`	생성 시점의 쿠폰 상태입니다.
`startsAt`	`RFC 3339 \| null`	사용 시작 시각입니다.
`expiresAt`	`RFC 3339 \| null`	사용 만료 시각입니다.

store.coupon.created 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.coupon.created",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "couponId": "202607190030",
    "name": "첫 구매 10%",
    "discountType": "percent",
    "discountAmount": "0",
    "discountBps": 1000,
    "status": "active",
    "startsAt": "2026-07-19T00:00:00.000Z",
    "expiresAt": "2026-08-19T00:00:00.000Z"
  }
}

전달 시점

무제한 재고가 아닌 상품 수량이 5 이하로 처음 내려갈 때

data 필드

필드	형식	설명
`productId*`	`12자리 숫자`	재고가 부족해진 상품 ID입니다.
`productName*`	`string`	현재 상품명입니다.
`quantity*`	`integer`	변경 후 남은 재고 수량입니다.
`threshold*`	`integer`	부족 판단 기준이며 현재 5입니다.

store.inventory.low 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.inventory.low",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "productId": "202607190003",
    "productName": "라이선스",
    "quantity": 5,
    "threshold": 5
  }
}

수량이 이미 5 이하인 상태에서 더 감소해도 새 이벤트가 발생하지 않습니다. 5를 초과했다가 다시 5 이하가 되면 다시 발생합니다.

연결 테스트

전달 시점

Webhook Endpoint 화면 또는 Open API에서 테스트 전송을 요청할 때

data 필드

필드	형식	설명
`webhookId*`	`12자리 숫자`	테스트 대상 Endpoint ID입니다.
`storeName`	`string`	대시보드에서 테스트했을 때의 스토어 이름입니다.
`requestedByUserId`	`12자리 숫자`	대시보드에서 테스트를 요청한 관리자 사용자 ID입니다.
`requestedByOpenApiKeyId`	`12자리 숫자`	Open API에서 테스트를 요청한 경우의 API Key ID입니다.

webhook.test 예제

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "webhook.test",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "webhookId": "202607190040",
    "storeName": "Test",
    "requestedByUserId": "202607190002"
  }
}

테스트 이벤트는 선택한 Endpoint 한 곳에만 전달됩니다.
requestedByUserId와 requestedByOpenApiKeyId 중 요청 경로에 해당하는 필드만 전달됩니다.

store.charge.*는 기존 충전 거래와의 호환성을 위한 이벤트입니다. 신규 주문 결제 연동에는 store.order.*를 사용합니다. 선택 옵션은 식별자와 표시명만 전달하며 구매자가 직접 입력한 원문과 원가는 포함하지 않습니다.

요청 형식

요청 헤더 예시

POST /webhooks/quartz HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
User-Agent: Quartz-Vend-Webhook/1.0
X-Quartz-Delivery: 7f8d6b34-5ac7-4f1a-bdc2-3529228bc1af
X-Quartz-Event: store.order.fulfillment_pending
X-Quartz-Event-ID: 5a8b6cf2-6b44-4a16-a764-99d2be7c31f8
X-Quartz-Event-Version: 2026-07-18
X-Quartz-Timestamp: 1785805323
X-Quartz-Signature: v1=<64자리 HMAC-SHA256 hex>

등록 URL의 경로와 쿼리를 유지해 전송합니다. 리디렉션을 수신 경로로 사용하지 않습니다. 호환 헤더 X-Quartz-Delivery-ID와 X-Quartz-Event-Type도 함께 전송됩니다.

공통 본문 필드

필드	형식	설명
`id*`	`UUID`	업무 이벤트 ID입니다. 여러 Endpoint에 전달되어도 같은 값을 사용합니다.
`type*`	`string`	구독한 canonical 이벤트 이름입니다.
`version*`	`string`	Webhook payload 계약 버전입니다.
`storeId*`	`12자리 숫자`	이벤트가 발생한 스토어 ID입니다.
`occurredAt*`	`RFC 3339`	업무 이벤트가 실제로 발생한 시각입니다.
`data*`	`object`	이벤트마다 구조가 달라지는 데이터입니다. 아래 이벤트별 항목에서 확인합니다.

store.order.fulfillment_pending · 본문 예시

{
  "id": "5a8b6cf2-6b44-4a16-a764-99d2be7c31f8",
  "type": "store.order.fulfillment_pending",
  "version": "2026-07-18",
  "storeId": "202603290001",
  "occurredAt": "2026-07-19T01:02:03.000Z",
  "data": {
    "orderId": "202607190001",
    "orderNumber": "#202607190001",
    "status": "paid",
    "buyer": {
      "userId": "202607190002",
      "nicknameSnapshot": "구매자"
    },
    "currency": "KRW",
    "subtotalAmount": "24000",
    "discountAmount": "0",
    "totalAmount": "24000",
    "lineItems": [
      {
        "orderLineId": "202607190001",
        "productId": "202607190003",
        "productNameSnapshot": "라이선스",
        "quantity": 2,
        "unitPrice": "12000",
        "lineTotal": "24000",
        "selectedOptions": []
      }
    ]
  }
}

서명 검증

알림이 Quartz에서 보낸 것인지 수신 서버에서 확인합니다. 아래 Node.js 예제를 사용할 수 있습니다.

webhook-server.js

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const WEBHOOK_SECRET = process.env.QUARTZ_WEBHOOK_SECRET;
if (!WEBHOOK_SECRET) throw new Error("QUARTZ_WEBHOOK_SECRET is required");

app.post("/webhooks/quartz", express.raw({ type: "application/json" }), async (req, res) => {
  const timestamp = req.header("X-Quartz-Timestamp") ?? "";
  const deliveryId = req.header("X-Quartz-Delivery") ?? "";
  const received = req.header("X-Quartz-Signature") ?? "";
  const rawBody = req.body.toString("utf8");

  const unixSeconds = Number(timestamp);
  const validDeliveryId = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(deliveryId);
  if (!validDeliveryId || !/^v1=[0-9a-f]{64}$/.test(received) ||
      !Number.isFinite(unixSeconds) || Math.abs(Date.now() / 1000 - unixSeconds) > 300) {
    return res.status(401).send("invalid timestamp");
  }

  const signedPayload = `${timestamp}.${deliveryId}.${rawBody}`;
  const expected = `v1=${createHmac("sha256", WEBHOOK_SECRET)
    .update(signedPayload)
    .digest("hex")}`;
  const actualBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  if (actualBuffer.length !== expectedBuffer.length ||
      !timingSafeEqual(actualBuffer, expectedBuffer)) {
    return res.status(401).send("invalid signature");
  }

  // deliveryId를 DB의 unique key로 저장한 뒤 업무 큐에 넣어요.
  const event = JSON.parse(rawBody);
  await enqueueQuartzEvent({ deliveryId, event });
  return res.sendStatus(204);
});

원문으로 검증

X-Quartz-Timestamp가 현재 시각과 5분 이내인지 확인합니다. JSON 파싱 전에 원문 HMAC을 timing-safe 방식으로 비교합니다. Express에서는 해당 경로에 express.json()보다 먼저 express.raw()를 적용합니다. 검증하지 않은 이벤트로 지급·환불을 실행하지 않습니다.

필터와 전달 필드

설정	동작
filters	이벤트의 필드·값 조건에 맞는 경우만 전달합니다.
allowFields	비어 있으면 비공개 정보가 제거된 data를 전달합니다. 지정하면 해당 data.* 경로만 남깁니다.
anonymizeFields	허용 필드 처리 후 지정 경로를 제거합니다. 배열 경로에는 *를 사용할 수 있습니다. 기본 제거 경로는 data.content와 data.images입니다.
항상 제외	이메일·비밀번호·토큰·인증 헤더·쿠키·계좌번호·지급 내용·재고 원문·사용자 입력값은 설정과 관계없이 제외합니다.

필터 및 전달 정책 예시

{
  "filters": {
    "type": "store.order.fulfilled",
    "data.currency": [
      "KRW",
      "USD"
    ]
  },
  "allowFields": [
    "data.orderId",
    "data.status",
    "data.totalAmount"
  ],
  "anonymizeFields": [
    "data.lineItems.*.selectedOptions"
  ]
}

실패와 재시도

조건	처리
2xx	전송 완료. 이후 업무 실패는 수신 서버의 큐에서 재처리합니다.
네트워크 오류·타임아웃	자동 재시도
408·409·425·429·5xx	자동 재시도. Retry-After는 최대 1시간까지 반영합니다.
재시도 간격	최대 5회 시도. 첫 지연은 약 30초이며 지수 백오프와 jitter를 적용합니다.
재시도 소진	dead_letter 상태. 대시보드에서 확인하고 수동 재시도할 수 있습니다.
410	수신 주소 폐기로 간주합니다. 같은 주소에서 3회 누적되면 자동 비활성화합니다.

이미 처리한 Delivery ID에는 업무를 반복하지 않고 2xx를 반환합니다. 일시 장애에 410을 사용하지 말고 5xx 또는 429와 Retry-After로 응답합니다.

Webhook

수신 주소 등록

전달 규칙

이벤트 참조

주문

store.order.created주문 생성

store.order.paid결제 완료

store.order.fulfillment_pending지급 대기

store.order.fulfilled지급 완료

store.order.failed지급 실패

store.order.exchanged교환 지급

store.order.cancelled지급 전 환불

store.order.refunded전체·부분 환불 접수

기존 충전 거래 (호환)

store.charge.created충전 요청 생성

store.charge.status_changed충전 상태 변경

후기

store.review.created후기 작성

store.review.updated후기 수정

store.review.hidden후기 숨김

쿠폰과 재고

store.coupon.created쿠폰 생성

store.inventory.low재고 부족

연결 테스트

webhook.test테스트 전송

요청 형식

공통 본문 필드

서명 검증

필터와 전달 필드

실패와 재시도