아임포트 Webhook


이 문서는 아임포트 webhook을 사용하여 아임포트 서버에 저장된 결제 정보를 가맹점 서버에 동기화하고 네트워크 불안정성을 보완하는 방법을 설명합니다.

Webhook이란?

Webhook(웹훅)이란, 특정 이벤트가 발생하였을 때 타 서비스나 응용프로그램으로 알림을 보내는 기능입니다. Webhook 프로바이더는 해당 이벤트가 발행하면 HTTP POST 요청을 생성하여 callback URL(endpoint)로 이벤트 정보을 보냅니다. 주기적으로 데이터를 폴링(polling)하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신측면에서 훨씬 더 효율적입니다. Webhook을 활용하면 커스텀 기능이나 다른 애플리케이션과 연동하여 기능을 확장할 수 있습니다.

콜백 함수를 통해 결제완료에 대한 고지를 받는데 왜 Webhook이 존재하나요?

아임포트 서버에서 클라이언트에 응답을 전달할 때 Wi-Fi 연결 끊김, 혹은 브라우저 자동 리로드 등의 이유로 클라이언트에서 결제 완료에 대한 응답을 받지 못하는 경우가 간헐적으로 발생합니다. 이런 경우를 대비해서 아임포트 서버에서 가맹점 서버로 webhook 이벤트를 발송하여 결제 정보를 동기화할 수 있도록 합니다.
아임포트 webhook은 다음과 같은 경우에 호출됩니다. Webhook은 추천 설정이며, 단, 가상 계좌 결제를 지원하는 경우 webhook을 사용하여 가상 계좌 입금에 대한 알림을 설정해야 합니다.
  • 결제가 승인되었을 때(모든 결제 수단) - (status : paid)
  • 가상계좌가 발급되었을 때 - (status : ready)
  • 가상계좌에 결제 금액이 입금되었을 때 - (status : paid)
  • 예약결제가 시도되었을 때 - (status : paid or failed)
  • 관리자 콘솔에서 환불되었을 때 - (status : cancelled)
Webhook 이벤트가 호출되면 설정한 URL endpoint에 대해 다음과 같은 POST 요청이 생성됩니다.
  curl -H "Content-Type: application/json" -X POST -d '{ "imp_uid": "imp_1234567890", "merchant_uid": "order_id_8237352", "status": "paid" }' { NotificationURL }
Webhook POST 요청의 본문은 다음의 정보를 포함합니다. 가맹점 서버는 해당 정보를 수신하고 아임포트 서버에서 결제 정보를 조회하여 검증 및 저장할 수 있습니다.
  • imp_uid: 결제번호
  • merchant_uid: 주문번호
  • status: 결제 결과

Callback URL 설정하기

아임포트 webhook이 호출될 때 결제 정보를 통보받을 URL을 설정하려면 아임포트 관리자 콘솔 내 시스템설정 페이지 > 웹훅(Notification)설정 탭을 선택합니다. 상단의 웹훅(Notification)발송 공통 URL란에 전 단계에서 복사한 값을 입력하고, 하단의 웹훅설정 저장 버튼을 눌러 설정을 저장합니다.

Content-Typeapplication/json 또는 application/x-www-form-urlencoded으로 지정할 수 있습니다.

Callback URL 필드 우측의 호출 테스트 버튼을 누르면 해당 URL을 호출하여 테스트할 수 있습니다.

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

기본적으로 webhook 호출 테스트는 외부망에서 접근 가능한 도메인만 가능합니다. localhost의 경우, 로컬머신 혹은 같은 망을 공유하고 있는 경우에만 접근이 가능하기 때문에, 아임포트에서 localhost로 callback URL을 호출할 수 없습니다.

하지만 ngrok 이라는 서비스를 통해 localhost를 외부망에서 접근 가능한 도메인으로 포워딩 하면 해당 도메인을 callback URL로 설정할 수 있습니다.

다음은 localhost:3000으로 실행된 개발환경을 ngrok 을 이용해서 외부 접속 가능한 도메인으로 포워딩하는 예제입니다. 해당 도메인을 callback URL로 설정하면 호출 테스트를 할 수 있습니다.

Webhook 구현하기

결제, 가상 계좌 발급 또는 입금, 및 환불 완료 후 처리 구현 방법은 일반결제 연동하기 문서의 Webhook을 이용하여 알림 설정하기를 참고하세요.

예약결제(정기결제) 시도 후 처리 구현 방법은 정기결제 연동하기 문서의 결제 예약하기를 참고하세요.

Webhook 요청 검증하기

아임포트 webhook이 호출되어 생성한 요청은 가맹점 서버의 엔드포인트(endpoint)가 처리합니다. 해당 엔드포인트는 공개된 URL이기 때문에 요청의 클라이언트(client IP)가 아임포트(Iamport IP)인지 반드시 확인해야 합니다.

아임포트 webhook이 호출되면 다음의 두 가지 고정된 IP로부터 요청이 생성됩니다. 해당되는 client IP는 아임포트로 간주하고 아니면 무시하면 됩니다.
  • 52.78.100.19
  • 52.78.48.223

IP가 추가될 수 있나요?

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

결제 흐름의 차이

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

다만, 아임포트를 사용하면 결제 처리의 흐름이 바뀌면서 결제 데이터를 가맹점 서버에 동기화하는 방식도 달라지게 됩니다. 결제가 발생했을 때, 먼저 아임포트 데이터베이스에 결제 데이터가 저장되고, 그 후에 webhook 또는 브라우저 리디렉션을 통해서 가맹점 데이터베이스에 결제 정보를 저장하게 됩니다.
1PG모듈 직접 연동
다음은 가맹점이 PG모듈과 직접 결제를 연동하는 흐름입니다.
  1. 가맹점 결제 페이지를 통해 주문 및 카드 정보를 입력하여 가맹점 서버에 결제를 요청한다.
  2. 가맹점 서버는 PG서버에 전달받은 결제 요청을 전달한다.
  3. PG서버는 전달받은 결제 정보로 카드사에 승인을 요청한다.
  4. 카드사 서버는 PG서버에 승인 결과를 응답한다.
  5. PG서버는 가맹점 서버로 결제 결과를 전달한다.
  6. 가맹점 서버는 결제 결과를 데이터베이스에 저장하고 결제 페이지에 출력한다.
2아임포트로 결제 연동
다음은 가맹점이 아임포트를 통해 결제를 연동하는 흐름입니다.
  1. 가맹점 결제 페이지를 통해 주문 및 카드 정보를 입력하여 아임포트 서버에 결제를 요청한다.
  2. 아임포트 서버는 PG서버에 전달받은 결제 요청을 전달한다.
  3. PG서버는 전달받은 결제 정보로 카드사에 승인을 요청한다.
  4. 카드사 서버는 PG서버에 승인 결과를 응답한다.
  5. PG서버는 아임포트 서버에 결제 결과를 전달한다.
  6. 아임포트 서버는 결제 결과를 데이터베이스에 저장하고 webhook을 통해 결제 정보를 가맹점 서버에 전달한다.
  7. 고객의 브라우저에 302 redirect 응답(Location: m_redirect_url)을 전달한다.
  8. 302 redirect 응답으로 인해 callback이 실행되거나 m_redirect_url로 리디렉션될 때 결제 정보를 가맹점 서버에 전달한다. 가맹점 서버는 결제 정보를 데이터베이스에 저장한다.

서버가 결제 정보를 수신 하는 순서는 보장되지 않습니다

기본적으로 아임포트 서버에서 webhook 호출 후 응답을 기다리지 않고 클라이언트에 302 redirect 응답을 보내기 때문에 결과 도달에 대한 순서를 보장하지 않습니다. 다만 가맹점 요청이 있을 경우 webhook 호출에 대한 응답을 받고 클라이언트에 302 redirect 응답을 보내어 순서를 보장해드리고 있습니다.