아임포트docs

아임포트 Webhook

아임포트 Webhook을 사용함으로써 아임포트 서버에 저장된 데이터를 서버에 동기화하고 네트워크 불안정성을 보완할 수 있습니다.

Webhook이란?

Webhook(웹훅)이란, 서버에서 어떠한 작업이 수행 되었을 때 해당 작업이 수행되었음을 HTTP POST로 알리는 개념을 말합니다. Webhook을 구현한 웹 애플리케이션은, 특정 작업이 수행될 때 URL에 대해 POST방식으로 요청을 생성합니다. 이 때, url(콜백 url)은 웹 애플리케이션을 사용하는 유저가 자신의 URL을 지정할 수 있습니다.

유저의 입장에서는 지속적으로 데이터를 폴링(polling)하여 대부분의 경우 불필요한 정보를 받는 대신, webhook을 활용하여 중요한 이벤트가 발생했을 때에만 정보를 수신할 수 있습니다. 이를 활용하여 유저의 커스텀 기능이나 다른 애플리케이션과 통합하거나 기능을 확장할 수 있습니다.
아임포트 webhook은 다음과 같은 경우에 호출됩니다.
  1. 결제가 승인되었을 때(모든 결제 수단) - (status : paid)
  2. 가상계좌가 발급되었을 때 - (status : ready)
  3. 가상계좌에 결제 금액이 입금되었을 때 - (status : paid)
  4. 예약결제가 시도되었을 때 - (status : paid or failed)
  5. 대시보드에서 환불되었을 때 - (status : cancelled)
Webhook이 호출되면 설정한 콜백 url에 대해 다음과 같은 POST요청을 생성합니다.
  curl -H "Content-Type: application/json" -X POST -d '{ "imp_uid": "imp_1234567890", "merchant_uid": "order_id_8237352", "status": "paid" }' { NotificationURL }
Webhook이 호출되어 생성되는 POST요청의 body에는 imp_uid, merchant_uid, status속성이 포함되어있습니다. imp_uid는 아임포트 주문번호, merchant_uid는 가맹점 주문번호, 그리고 status는 결제 결과를 나타냅니다.

콜백 url 에서 수신한 imp_uid와 merchant_uid를 통해 아임포트 REST API를 활용하여 결제 정보를 조회한 후, 해당 데이터를 가맹점 서버에 동기화할 수 있습니다.

콜백 url 설정하기

아임포트 webhook이 호출될 때 결제 정보를 통보받을 콜백 url은 아임포트 대시보드에서 시스템 설정 > PG연동 설정 하단의 결제 직후 Notification URL 필드에서 설정할 수 있습니다. HTTP 요청의 url을 입력하고 Content-Type을 application/json 또는 application/x-www-form-urlencoded으로 지정할 수 있습니다.

localhost로 호출테스트는 못하나요?

기본적으로 웹훅 호출 테스트는 외부망에서 접근 가능한 도메인만 테스트가 가능합니다. localhost의 경우 작업중인 머신(데스크탑, 랩탑) 혹은 같은 망을 공유하고 있는 경우만 접근 가능한 alias이기 때문에, 아임포트에서 localhost로 호출 테스트를 위한 HTTP 요청을 보낼 방법이 없습니다.

하지만 ngrok 이라는 서비스를 통해 localhost를 외부망에서 접근 가능한 도메인으로 포워딩 시키면 로컬머신에서 개발중인 localhost도 웹훅 호출 테스트가 가능합니다. 위 이미지는 localhost:3000 으로 띄운 개발환경을 ngrok 을 이용해서 외부접근가능한 도메인으로 포워딩하는 예시입니다. 예시를 통해 생성된 도메인을 시스템 설정 > PG연동 설정 하단의 결제 직후 Notification URL에 입력하시면 정상적으로 테스트가 가능합니다.

결제 흐름의 차이

아임포트는 편리한 결제 연동을 위해 지금까지 직접 PG서버와 통신해야 했던 가맹점 서버의 역할을 대신합니다. PG서버와 직접 통신하기 위해서는 PG사가 지원하는 제한적인 개발환경을 사용할 수 밖에 없었고 PG모듈을 컴파일하고 설치하는 등의 복잡한 절차를 가맹점 서버에서 해야했습니다. 하지만 아임포트를 사용하여 이러 불편함 없이 간결한 표준 속성과 REST API를 통해 쉽고 편리하게 결제를 연동할 수 있습니다.

다만, 아임포트를 사용함으로써 결제 처리의 흐름이 변화함에 따라 가맹점 서버의 결제 데이터를 동기화하는 방식이 달라지게 됩니다. 결제가 발생했을 때, 먼저 아임포트 데이터베이스에 결제 데이터가 저장되고, 그 후에 webhook 또는 브라우저 redirection을 통해서 가맹점의 데이터베이스에 결제 정보를 저장하게 됩니다.
1PG모듈 직접 연동
가맹점이 PG모듈을 직접 연동하면 위의 도식과 같은 흐름이 이루어 집니다. 먼저, 고객 브라우저가 주문화면을 통해 주문 정보와 카드 인증 정보를 가맹점 서버에 전달합니다. 그 후 가맹점 서버는 PG서버에 주문 정보와 카드 인증정보를 전달하여 결제를 요청합니다. PG사는 전달받은 정보를 카드사에게 전달하여 결제 승인을 요청하고, 그 승인 결과를 가맹점 서버에 응답합니다. 가맹점 서버는 PG사로부터 전달받은 승인 결과를 가맹점 데이터베이스에 저장합니다. 그 후 거래 결과를 고객 브라우저에 표시합니다.
2아임포트로 결제 연동
가맹점이 아임포트를 통해 결제를 연동하면 위의 도식과 같은 흐름이 이루어 집니다. 먼저, 고객 브라우저가 주문화면을 통해 주문정보와 카드 인증 정보를 아임포트 서버에 전달합니다. 그 후 아임포트 서버는 PG서버에 주문 정보와 카드 인증정보를 전달하여 결제를 요청합니다. PG사는 전달받은 정보를 카드사에게 전달하여 결제 승인을 요청하고, 그 승인 결과를 아임포트 서버에 응답합니다. 아임포트 서버는 PG사로부터 전달받은 승인 결과를 아임포트의 데이터베이스에 저장합니다.

그 후, 아임포트 서버는 webhook이 호출되어 결제 정보를 가맹점 서버에 전달합니다. 그 후 고객의 브라우저에 302 redirect 응답(Location: m_redirect_url)을 생성합니다. 그러면 고객의 브라우저의 callback이 실행되거나 m_redirect_url로 redirection될 때 결제 정보를 가맹점 서버에 전달합니다. 두가지 경로를 통해 결제 정보를 전달받은 가맹점 서버는 전달받은 정보를 활용하여 거래 정보를 가맹점 데이터베이스에 저장합니다.

Webhook 활용하기

아임포트의 webhook은 다음과 같이 활용할 수 있습니다.
1결제 데이터 누락 가능성 보완하기
고객의 브라우저가 아임포트 서버의 302 redirect 응답(Location: m_redirect_url)을 수신했으나, 고객 결제 기기의 네트워크 불안정성, 브라우저의 갑작스러운 종료 등으로 인해 해당 url에 대한 GET요청의 생성에 실패하는 경우가 발생할 수 있습니다. 따라서 webhook을 활용하여 아임포트 서버로부터 수신되는 결제 정보를 통해 데이터동기화 누락을 막을 수 있습니다.
2가상계좌 입금 후 통보받기
고객의 결제수단이 가상계좌일 때, 가상계좌 발급 후 미래의 어느 시점에 고객이 가상계좌에 입금을 했을때 가맹점 서버의 데이터베이스에 고객이 입금을 했다는 것을 업데이트 해야합니다. 아임포트 webhook을 활용하여 입금 여부의 업데이트를 자동화 할 수 있습니다. 가상계좌에 결제 금액이 입금되었을 때 호출되므로 콜백 url에서 결제 정보를 수신한 뒤 결제 상태를 조회하여 가상계좌 입금 여부를 판단한 뒤 가맹점의 데이터베이스를 동기화할 수 있습니다.
3예약결제(정기결제) 시도 후 처리하기
아임포트 REST API인 /subscribe/payments/schedule를 활용하여 미래 시점의 결제를 예약할 수 있습니다. 이때, 예약된 결제가 시도되면 webhook이 호출되어 결제 정보를 콜백 url에 대해 전달합니다. 이때 가맹점은 수신된 결제 정보를 통해 결제 성공여부를 확인하고 결제가 성공했으면 다음 결제를 예약하여 정기적인 결제를 구현할 수 있습니다.

Webhook 구현 방법

결제 데이터 누락 가능성 보완과 가상계좌 입금 후 통보 설정은 일반결제 연동하기 문서의 Webhook 및 데이터동기화 설정하기 항목에서 구현방법을 확인할 수 있습니다.

예약결제(정기결제) 시도 후 처리 설정은 정기결제 연동하기 문서의 결제 예약하기 항목에서 구현방법을 확인할 수 있습니다.

요청 검증하기

아임포트의 Webhook이 호출되어 생성한 요청을 가맹점 서버의 엔드포인트(endpoint)가 처리하게 됩니다. 해당 엔드포인트는 공개된 url이기 때문에 요청의 클라이언트(client)가 아임포트인지 반드시 확인해야 합니다. 요청을 검증하기 위해서는 요청 클라이언트의 IP가 아임포트의 IP인지 확인하여 판단할 수 있습니다.

아임포트는 웹훅이 호출되면 아래의 두 가지 고정된 IP로부터 요청이 생성됩니다. - 52.78.100.19 - 52.78.48.223따라서 Webhook호출로 인해 생성된 요청을 처리하는 엔드포인트에서는, 전달받은 요청 클라이언트의 IP가 위의 두 IP에 해당하는지 확인하여, 해당 요청을 아임포트가 생성한 것인지 판단할 수 있습니다. 요청의 IP가 위 두 IP가 아니라면, 무시하면 됩니다.

IP가 추가될 수 있나요?

아임포트는 NAT 게이트웨이를 사용하여 Webhook 요청의 IP는 위의 두 가지로 고정되어있습니다. 차후에 아임포트의 서버가 증설되어도 IP는 추가되지 않고 위의 두 IP로 고정됩니다.