Webhook V1 지원 종료 안내V2 출시로 인하여 V1 웹훅은 공식적으로 지원이 종료되었습니다. V2로 업그레이드를 진행해주시고 업그레이드가 완료된 후에는 이전 버전 웹훅의 연동을 해지해주시기 바랍니다. ‘비관리형 결제’를 이용하시는 경우에는 기존 결제 웹훅을 해지하지 않으셔도 됩니다. 연동 해지는 ‘스텝페이 포탈 > 설정 > 웹훅 설정’에 접속하시고 상단의 버전을 V1으로 변경해주시면 됩니다.
연관 가이드
사전 준비 작업
웹훅을 사용하려면 스텝페이 포탈에서 [설정 → 결제 설정 → 웹훅 설정]으로 이동해 웹훅을 등록해야 합니다.
웹훅 이벤트 유형
스텝페이의 웹훅 이벤트는 다음과 같습니다. 이벤트 유형별로 연동 설정이 가능하며, 각 이벤트는 특정 상황에서 발생합니다.
| 이벤트 유형 | 설명 |
|---|
| 주문 | 갱신 주문이 성공했을 때 호출됩니다. 최초 주문은 호출되지 않습니다. |
| 구독 | 구독의 상태가 변경되었을 때 호출됩니다. 최초 생성시에도 호출됩니다. |
| 결제 | 비관리형 결제 사용 시 제공되는 웹훅입니다. (결제 가이드 > 비관리형(Self) 결제 가이드 > 결제 웹훅) |
주의사항
웹훅은 인증 없이 동작하기 때문에 웹훅 엔드포인트 주소가 노출될 경우 악용될 가능성이 있습니다. 따라서 웹훅을 통해 전달받은 정보는 항상 백엔드에서 한 번 더 주문이나 결제 또는 구독에 대한 검증을 거친 후에 처리하시기 바랍니다.
연동 가이드
아래에서는 각 웹훅 이벤트에 대해 어떤 정보를 받을 수 있는지, 그리고 이 정보를 어떻게 사용해야 하는지에 대해 설명합니다.
주문 웹훅
갱신 주문이 성공했을 때 발생하며, 이를 통해 실시간으로 성공 알림을 받을 수 있습니다. 실패했을 때는 웹훅이 전송되지 않습니다. 단, 최초 주문시엔 발생하지 않습니다.
요청 형식
| HTTP Method | POST |
|---|
| Content-Type | application/json |
웹훅 본문
| Feild | Type | Required | Description |
|---|
| webHookType | String | 필수 | 웹훅 타입 |
| orderId | Long | 필수 | 주문 번호 |
웹훅 타입
지원하는 웹훅 타입은 아래와 같지만 ‘주문 웹훅’의 경우 ‘PAYMENT’만 전달됩니다.
| 상태 | 설명 |
|---|
| PAYMENT | 결제 완료 |
| VBANK | 가상계좌 발급 완료 |
| CANCELED | 결제 취소 완료 |
| USER_CANCELED | 결제창에서 취소버튼을 눌렀을 때 |
| FAILED | 결제 실패 |
| CMS | CMS로 최초 결제 |
| BILLKEY (deprecated) | 결제 완료 (0원인 경우)
-PAYMENT 로 변경 예정 |
{
"webHookType": "PAYMENT",
"orderId": 1
}
주문 웹훅이 발송되지 않는 경우
- 최초 주문일 때
- 단건 주문일 때
- 구독 주문 갱신 시, 결제 실패일 때
- 구독 주문 갱신 시, 결제 금액이 0원일 때
구독 웹훅
구독 상태 변경 웹훅은 구독의 상태가 변경되었을 때 발생합니다. 구독의 상태가 활성화, 일시정지, 만료 등으로 변경되었을 때 실시간으로 이를 알 수 있습니다. 구독 최초 생성 시에도 웹훅이 발생합니다.
요청 형식
| HTTP Method | POST |
|---|
| Content-Type | application/json |
웹훅 본문
| Feild | Type | Required | Description |
|---|
| id | Long | 필수 | 구독 번호 |
| status | String | 필수 | 구독 상태 |
구독 상태
| 구독 상태 | 설명 |
|---|
| ACTIVE | 활성화 |
| UNPAID | 결제 실패 |
| PENDING_PAUSE | 일시정지 예정 |
| PAUSE | 일시 정지 |
| PENDING_CANCEL | 취소 예정 |
| EXPIRED | 구독 만료 |
| CANCELED | 사용자에 의한 취소 |
{
"id": 1,
"status": "ACTIVE"
}
