가맹점 서버의 웹훅 수신 처리를 실제 결제 없이 확인할 때 씁니다. 부트페이가 준비한 샘플 결제 완료 주문으로 order.done 웹훅을 한 번 보냅니다. 쇼핑몰의 실제 주문 데이터는 쓰지 않습니다.
POST /v1/webhook/test
샘플 order.done 웹훅 발송을 예약하고, 보낼 내용을 바로 돌려줍니다. 발송은 약 1초 뒤 비동기로 이뤄지며 재시도는 1회로 제한됩니다. 수신 서버가 응답하지 않아도 이 API 의 응답은 성공입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:webhook_test—Bootpay-Role: supervisor로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401API_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 를 부여받아야 합니다
