입금 알림 웹훅으로 간편하게 받는 방법

쇼핑몰을 운영한다면 가상계좌는 꼭 필요해요. 고객이 번거로운 본인인증 과정을 거치지 않고 안전한 현금 결제를 할 수 있기 때문인데요. 고객에게 가상계좌를 발급했다면, 고객이 입금한 것을 확인하고 상품을 발송해야 돼요.

입금을 확인하려면 일정 간격으로 결제 조회 API를 호출할 수도 있어요. 이것은 폴링(Polling) 방법인데요. 비효율적이고 요청 제한에 걸릴 수 있어서 토스페이먼츠 서비스에는 사용하면 안 돼요. 폴링 대신 웹훅(Webhook)을 사용해보세요. 웹훅은 폴링과 달리, 한번 설정하면 알림을 실시간으로 받을 수 있어요. 비유를 들자면 폴링은 친구가 받을 때까지 계속 전화하는 것과 같고, 웹훅은 친구에게 "시간 나면 전화 줘"라고 문자를 남기는 것과 같죠.

웹훅이 무엇이고, 언제 사용하면 유용한지 알아보고 토스페이먼츠 가상계좌 웹훅을 연동하는 방법을 알려드릴게요.

웹훅이란?

웹훅은 알림을 보내는 방법이에요. 서비스마다 웹훅 사용 방법이 조금씩 다르겠지만, 모든 서비스에는 웹훅 ‘엔드포인트’를 등록해야 돼요. 엔드포인트는 알림의 목적지라고 생각할 수 있어요. 휴대폰의 전화번호 역할을 하는 것이죠. 특정 이벤트가 일어나면, 웹훅은 엔드포인트로 이벤트 정보가 담긴 페이로드를 전송해요. API를 호출하는 것과 반대되기 때문에 웹훅은 ‘역방향 API’라고도 부르고요. 서비스에 따라 웹훅을 검증하는 시크릿 값을 제공할 수도 있고, 웹훅을 잘 받았다는 응답을 강제할 수도 있어요.

토스페이먼츠 웹훅은 이렇게 연동할게요.

  1. 토스페이먼츠가 내 엔드포인트로 페이로드 전송
  2. 내 서버에서 필요한 액션 실행
  3. 200 응답을 토스페이먼츠로 전송

토스페이먼츠 웹훅 연동해보기

가상계좌 웹훅을 연동해서 ‘입금 완료’ 이벤트 페이로드를 받아볼게요. 먼저, 토스페이먼츠 개발자센터에 회원가입하세요. 이메일 주소, 휴대폰 번호만 있다면 간편하게 가입할 수 있어요. 로그인해서 나만의 테스트 API 키를 확인하세요. 클라이언트 키는 SDK를 연동할 때 사용하고, 시크릿 키는 API 인증할 때 사용해요. 시크릿 키는 클라이언트나 외부에서 접근할 수 있는 곳에 노출되지 않도록 주의해주세요.

1️⃣ 샘플 프로젝트 설정

결제위젯 샘플 프로젝트를 클론해서 node-ejs 예시를 사용할게요. 

$ git clone https://github.com/tosspayments/payment-widget-sample.git
$ cd node-ejs

/views/index.ejs 파일을 열어보세요. 결제위젯 SDK를 사용하는 간단한 주문서 페이지가 구현되어 있어요. 결제위젯을 초기화하는 코드에 내 클라이언트 키를 넣어볼게요.

const paymentWidget = PaymentWidget(
        "{MY_CLIENT_KEY}", // 내 클라이언트 키
        PaymentWidget.ANONYMOUS
      );

다음, /routes/index.js 파일을 확인할게요. Express로 서버를 실행하고 있어요. 해당 파일에 있는 secretKey를 개발자센터에서 받은 내 시크릿 키로 교체하고, 이벤트 페이로드를 받을 /hook엔드포인트를 만들게요. 웹훅 이벤트를 잘 받았다면 200 응답을 보내주는 코드도 구현해요. 토스페이먼츠 웹훅 이벤트를 받고 10초 이내로 200 응답을 보내야 해요. 안 그러면 웹훅 전송이 실패했다고 생각하고 일정 기간 뒤에 웹훅을 다시 전송해요.

var secretKey = "{MY_SECRET_KEY}"; // 내 시크릿 키

//...

// 웹훅 받을 엔드포인트 추가하기
router.post("/hook", function (req,res){
  console.log(req.body) // 웹훅 처리하는 코드 추가하기
  res.status(200).end() // 200 응답 보내기
})

2️⃣ 웹훅 등록

기본 설정은 완료됐으니, 아래 명령어로 패키지를 설치하고 샘플 프로젝트를 실행할게요.

$ npm install
$ npm start

http://localhost:8080 으로 샘플 앱이 실행되었습니다. 라는 메시지가 나오네요. 로컬 개발 환경에서 프로젝트가 실행됐어요. 하지만 웹훅은 온라인에서 접근 가능한 주소에서만 받을 수 있어요. 로컬 개발 환경은 외부에서 접근할 수 없기 때문에 로컬 서버를 노출해주는 ngrok을 활용할게요. localtunnel, localhost.run 등 다른 툴을 사용해도 괜찮아요.

ngrok을 잘 설치하고 ngrok http 8080 명령어를 실행하면 https://4c230-000.ngrok.io 와 같은 링크가 제공돼요. 링크 뒤에 /hook을 추가하면 아까 서버에 등록한 웹훅의 엔드포인트가 돼요. 예를 들어, https://4c230-000.ngrok.io/hook 와 같은 형태이죠.

웹훅 엔드포인트를 개발자센터에 등록할게요. 가상계좌 입금 이벤트를 받을 수 있는 DEPOSIT_CALLBACK 이벤트를 구독하세요.

3️⃣ 테스트 가상계좌 결제

이제 테스트 결제하고 웹훅 이벤트를 받을 차례에요. 샘플 프로젝트를 띄운 http://localhost:8080 로 이동하면 주문서 페이지가 나와요. 결제수단으로 가상계좌를 선택하고 임의 환불 계좌 정보를 넣으세요. 결제하기 버튼을 누르고 결제창에서 가상계좌를 발급받을 은행을 선택한 다음, 개발자센터 테스트 결제내역에서 입금처리를 할게요.

입금처리가 완료되면 아래와 같이 콘솔에 이벤트 페이로드가 찍히고 내 서버에서 200 응답을 잘 보냈네요. 개발자센터에 등록한 웹훅도 다시 보세요. 웹훅 전송 기록에 성공 내역이 찍힌 것을 확인할 수 있어요. 이벤트 발생 시간을 누르면 이벤트 페이로드 기록도 볼 수 있어요.

{
  createdAt: '2023-05-23T14:42:26.000000',
  secret: 'ps_Z1aOwX7K8mYpalqAGRwj8yQxzvNP',
  orderId: '3f9c765d-60ed-4735-8af5-ab9d1142a3e8',
  status: 'DONE',
  transactionKey: '83B3CD71DF004878066FEDCB7C21E775'
}
POST /hook 200 0.752 ms

웹훅으로 가상계좌 입금 알림을 받았다면 고객에게 상품을 발송해주세요. 이렇게 특정 이벤트가 발생하면 액션을 취해야 될 때 웹훅을 유용하게 사용할 수 있어요. 가상계좌 외에 다른 결제수단 상태 알림도 토스페이먼츠 웹훅으로 연동할 수 있어요.

라이브 환경 주의점

테스트를 끝냈다면 라이브 환경에서 웹훅을 연동해보세요. 라이브 환경에서는 아래 세 가지를 꼭 확인하세요.

✔️ 토스페이먼츠의 IP 주소를 방화벽에서 허용 해주세요.

✔️ 웹훅 이벤트 전송에 실패하면 최대 7회까지 다시 전송을 시도해요.

✔️ 가상계좌 결제 상태가 DONE에서 WAITING_FOR_DEPOSIT으로 바뀌면 고객에게 재입금 안내가 필요해요.

Writer 박수연 Graphic 이은호, 이나눔

토스페이먼츠의 모든 콘텐츠는 사업자에게 도움이 될 만한 일반적인 정보를 ‘참고 목적’으로 한정해 제공하고 있습니다. 구체적 사안에 관한 자문 또는 홍보를 위한 것이 아니므로 콘텐츠 내용의 적법성이나 정확성에 대해 보증하지 않으며, 콘텐츠에서 취득한 정보로 인해 직간접적인 손해가 발생해도 어떠한 법적 책임도 부담하지 않습니다.

ⓒ토스페이먼츠, 무단 전재 및 배포 금지

    의견 남기기