웹훅 테스트

가맹점 서버의 웹훅 수신 처리를 실제 결제 없이 확인할 때 씁니다. 부트페이가 준비한 샘플 결제 완료 주문​​으로 order.done 웹훅을 한 번 보냅니다. 쇼핑몰의 실제 주문 데이터는 쓰지 않습니다.

POST /v1/webhook/test

샘플 order.done 웹훅 발송을 예약하고, 보낼 내용을 바로 돌려줍니다. 발송은 약 1초 뒤 비동기로 이뤄지며 재시도는 1회​​로 제한됩니다. 수신 서버가 응답하지 않아도 이 API 의 응답은 성공입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:webhook_test — Bootpay-Role: supervisor 로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401 API_ROLE_NOT_SUPPORT
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body webhook_url string 쇼핑몰 웹훅 URL 웹훅을 받을 주소. 없으면 관리자에 설정한 웹훅 URL 로 보냅니다
body header_content_type integer 쇼핑몰 설정 본문 형식. 1 application/x-www-form-urlencoded, 2 application/json. 없거나 0 이면 쇼핑몰 설정을 따릅니다

응답

200 OK

{
  "webhook_job_id": "66f1...",
  "webhook_url": "https://example.com/bootpay/webhook",
  "webhook_data": {
    "project_key": "5f...",
    "idempotency_key": "8f14e45f-ceea-4e7a-9c1d-0b5d7a3c2e11",
    "webhook_type": "order.done",
    "payload": {
      "order_number": "2409231234567",
      "status": "payment_completed"
    }
  }
}json
필드 타입 설명
webhook_job_id string 예약된 웹훅 발송 작업 ID
webhook_url string 실제로 보낼 주소
webhook_data object 수신 서버가 받을 본문
webhook_data.project_key string 쇼핑몰(프로젝트) 식별자
webhook_data.idempotency_key string 이 발송의 멱등 키. 수신 측 중복 처리 방지에 씁니다. 테스트마다 새 값입니다
webhook_data.webhook_type string 항상 order.done
webhook_data.payload object 주문 데이터. 실제 결제 완료 웹훅과 같은 형식이며, 주문 상세의 주문 필드(order_number, status, price, products, user, receipt_success_data 등)로 이루어집니다

오류

HTTP error_code 언제
400 WEBHOOK_URL_BLANK webhook_url 을 보내지 않았고 관리자에도 웹훅 URL 이 없음
404 TEST_WEBHOOK_ORDER_NOT_FOUND 이 환경에 샘플 주문이 준비돼 있지 않음 (부트페이에 문의)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-03-05 추가
  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

함께 보기