콘텐츠로 이동

Toss Payments 결제 웹훅과 검증

개요

결제가 일어나고 끝나는 게 아니라, 그 상태가 바뀌었을 때 우리 서버가 알아야 구독을 열거나 닫아요. 토스페이먼츠는 결제 상태에 변경이 생기면 웹훅(Webhook) 으로 실시간 업데이트를 보내줘요. 결제 성공처럼 중요한 순간을 우리가 직접 폴링으로 쫓지 않아도, PG가 신호를 보내주는 거죠. 이 페이지는 공식 문서 기준으로 웹훅 이벤트 타입, 등록, 재전송 정책, 그리고 운영상 검증 요점을 풀어요.

핵심 개념

웹훅 이벤트 타입

토스 공식 문서는 웹훅으로 등록할 수 있는 이벤트 타입을 제시해요. 주요 타입은 이렇고, 각 이벤트마다 본문과 설명이 달라요.

이벤트 타입 설명
PAYMENT_STATUS_CHANGED 결제 상태 변경 이벤트. 모든 결제수단에 사용 가능.
DEPOSIT_CALLBACK 가상계좌 입금 및 입금 취소 이벤트.
CANCEL_STATUS_CHANGED 결제 취소 상태 이벤트.
METHOD_UPDATED (브랜드페이) 고객 결제수단 변경 이벤트.
CUSTOMER_STATUS_CHANGED (브랜드페이) 고객 상태 변경 이벤트.

웹훅 등록

개발자센터의 웹훅 메뉴에서 웹훅 이름과 URL을 입력하고 원하는 이벤트를 선택해 등록해요. 웹훅은 상점 아이디(MID)별로 설정되고, 각 MID에 따로 전송돼요. 미리 정의된 이벤트가 발생하면 등록한 URL로 웹훅이 전송돼요.

웹훅 전송 기록 확인

개발자센터 웹훅 목록에서 상세를 보면 전송 기록을 확인할 수 있어요. 하나의 전송 기록은 이벤트 발생 뒤의 상태 변화를 보여주고, 전송 상태는 '전송 중', '성공', '실패' 셋 중 하나예요. 이벤트 발생 시간을 선택하면 해당 이벤트 본문도 볼 수 있어요.

재전송 정책

웹훅을 잘 받았다면 10초 이내에 200 응답을 보내야 해요. 200 응답이 없고 최초 전송이 실패하면, 최대 7회까지 재전송돼요(최초 전송으로부터 3일 19시간 후까지). 재전송 간격은 1, 4, 16, 64, 256, 1024, 4096분으로 늘어나요. 1회부터 6회까지 실패해도 상태는 '전송 중'이고, 7회 실패하면 '실패'로 바뀌어요. 재전송 중일 때 '다시 시도'를 누르면 진행 중이던 재전송이 무효화되고 새 요청이 시도돼요.

취소·가상계좌 이벤트

가상계좌 결제는 DEPOSIT_CALLBACK으로 입금·입금 취소를, 취소는 CANCEL_STATUS_CHANGED로 받아요. 결제 수단에 따라 받는 이벤트 타입이 다르므로, 상품 형태에 맞춰 등록해야 해요.

실제 적용 (데이터스케쳐스)

웹사이트에서 상품을 팔 때, 결제가 성공했는지는 웹훅으로 확인하는 게 핵심이에요. PAYMENT_STATUS_CHANGED 이벤트가 성공 상태로 우리 서버에 오면 그제서야 구독·주문을 활성화해요. 결제는 프론트에서 일어나지만 "터미널 판단"은 서버가 웹훅으로 받아서 하죠.

운영에서 놓치기 쉬운 두 가지를 꼽자면 중복 처리와 놓친 이벤트예요. 같은 웹훅이 두 번 오거나, 우리 서버가 잠깐 죽어 이벤트를 놓치면 구독이 잘못 열리거나 열리지 않을 수 있어요. 그래서 같은 결제 신호를 한 번만 처리하는 멱등성을 설계하고, 웹훅을 놓친 경우를 대비해 주기적으로 결제 상태를 조회해 보정하는 흐름을 함께 두는 게 좋아요. 결제 자체를 어떻게 붙이는지는 결제 흐름(빌링)에서, 전체 결제 연동은 Toss Payments에서 이어져요.

더 알아보기