웹훅(Webhook)이란?
특정 이벤트가 발생하였을 때 타 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
- Webhook 프로바이더는 해당 이벤트가 발행하면 HTTP POST 요청을 생성하여 callback URL(endpoint)로 이벤트 정보을 보냅니다.
- 주기적으로 데이터를 폴링(polling)하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신측면에서 훨씬 더 효율적입니다.
- Webhook을 활용하면 커스텀 기능이나 다른 애플리케이션과 연동하여 기능을 확장할 수 있습니다.
- 포트원에서는 결제 완료 등 이벤트가 발생했을 때 고객사의 서버에 전송하고 있습니다.
- 이벤트가 발생하면 포트원 콘솔에 등록된 웹훅 URL로 HTTP POST 요청을 보냅니다.
고객사에서는 이 요청을 받아 최신 결제 정보로 동기화 하도록 구현해야 합니다.
웹훅 연동이 꼭 필요한가요?
안정적인 결제 처리를 위해 웹훅 연동을 강력히 권장합니다.
인터넷 연결 끊김, 브라우저 자동 새로고침 등의 이유로 클라이언트에서 결제 완료에 대한 응답을 받지 못하는 경우가 간헐적으로 발생합니다. 이런 경우 연동한 웹훅을 통해 누락 없이 결제 정보를 동기화할 수 있습니다.
인터넷 연결 끊김, 브라우저 자동 새로고침 등의 이유로 클라이언트에서 결제 완료에 대한 응답을 받지 못하는 경우가 간헐적으로 발생합니다. 이런 경우 연동한 웹훅을 통해 누락 없이 결제 정보를 동기화할 수 있습니다.
웹훅 발생 이벤트
포트원 웹훅은 다음과 같은 이벤트에 발생됩니다.
- 결제가 승인되었을 때(모든 결제 수단) - (status : paid)
- 가상계좌가 발급되었을 때 - (status : ready)
- 가상계좌에 결제 금액이 입금되었을 때 - (status : paid)
- 예약결제가 시도되었을 때 - (status : paid or failed)
- 관리자 콘솔에서 결제 취소되었을 때 - (status : cancelled)
⚠
결제 실패 시에는 웹훅이 호출되지 않아요!
웹훅 URL 설정
웹훅 URL을 설정하면 포트원에서 이벤트 발생 시 해당 URL로 웹훅을 전송합니다. URL은 관리자 콘솔에서 두 가지 형태로 지원하고 있습니다. 콘솔에서 설정했더라도 결제 시에 notice_url파라미터로 지정하여 호출하는 경우 해당 URL로 전송됩니다.
V2 웹훅 URL 설정 방법 보러가기↗
V1 웹훅 URL 설정 방법 보러가기↗
웹훅 재 전송이 가능한가요?
웹훅은 기본적으로 1회 전송되도록 설정되어 있습니다.
네트워크 에러가 발생하거나 고객사 응답(HTTP 상태 코드)이 500번대인 경우, 재발송 설정을 원하신다면 웹훅이 최대 5회까지 1분 간격으로 재시도될 수 있습니다.
네트워크 에러가 발생하거나 고객사 응답(HTTP 상태 코드)이 500번대인 경우, 재발송 설정을 원하신다면 웹훅이 최대 5회까지 1분 간격으로 재시도될 수 있습니다.
웹훅 재발송 방법 보러가기 ↗