웹훅은 데이터가 변경되었을 때 상점 서버에서 실시간으로 알림을 받을 수 있는 기능입니다.
알림을 받을 웹훅 URL을 만들고 등록해두면 결제 상태가 변경되었을 때, 요청해 둔 지급대행이 실행됐을 때, 브랜드페이에 고객이 결제 수단을 업데이트 했을 때와 같은 변경 사항을 알 수 있습니다.
- 웹훅을 이용해서 알림을 받고 싶은 이벤트 타입과 데이터 형식을 확인합니다.
- 웹훅 URL을 만든 뒤 개발자센터의 웹훅 페이지에서 등록합니다.
- 고객이 입금하거나 결제를 취소하는 등 상태 변경이 발생합니다.
- 등록해 둔 웹훅 URL로 전달받은 이벤트를 확인합니다.
등록한 웹훅 URL에 웹훅 전송 후 응답으로 HTTP 200 OK
이 돌아오지 않으면 전송 실패로 판단합니다. 최초의 웹훅 전송이 실패하면 성공할 때까지 최대 7회(최초 전송으로부터 3일 19시간 후)까지 웹훅을 재전송합니다.
재전송 간격은 1분 → 4분 → 16분 → 64분 → 256분 → 1024분 → 4096분으로 늘어납니다.
재전송 횟수 | 재전송 간격(분) |
---|---|
1 | 1 |
2 | 4 |
3 | 16 |
4 | 64 |
5 | 256 |
6 | 1024 |
7 | 4096 |
마지막 재전송까지 실패하면 이메일로 전송에 실패한 이벤트 정보를 알려드립니다. 이메일에 포함된 웹훅 이벤트 정보를 확인하고 상점 서버나 웹훅 URL에 이상이 있는지 점검해보세요.
웹훅은 HTTP POST 메서드를 사용해서 JSON 형태로 전달됩니다. 서버에서 JSON을 처리할 수 있는지 확인해주세요. HTTP도 지원하지만 보안을 위해 HTTPS로 통신하는 것을 권장합니다.
데이터가 변경되면 웹훅 이벤트가 발생합니다. 등록해 둔 웹훅 URL로 돌아오는 웹훅 이벤트 본문은 아래와 같은 형태입니다.
{
"eventType": "PAYMENT_STATUS_CHANGED",
"createdAt": "2022-05-12T00:00:00.000",
"data": {
"paymentKey": "",
"status": "DONE",
"orderId": ""
}
}
아래 필드들은 공통입니다.
eventType
: 웹훅의 이벤트 타입입니다.createdAt
: 웹훅이 생성될 때의 시간입니다. 이 값으로 웹훅이 발행된 순서를 알 수 있습니다. ISO 8601 형식인yyyy-MM-dd'T'HH:mm:ss.SSS
를 사용합니다.data
: 이벤트와 관련한 데이터입니다. 이벤트 타입에 따라 형태가 달라집니다. 아래 이벤트 타입 알아보기에서 살펴보세요.
응답으로 HTTP 200 OK
이 돌아올 경우 성공으로 판단하며, 이외에는 실패로 판단합니다. 실패할 경우 웹훅 재전송 정책에 따라 성공할 때까지 몇 차례 재전송합니다.
토스페이먼츠에서 지원하는 웹훅 이벤트 그룹은 크게 일반 결제, 지급대행, 브랜드페이 세 가지 입니다. 각 이벤트 그룹에서 지원하는 이벤트와 본문 형식을 알아봅니다.
PAYMENT_STATUS_CHANGED
: 결제 상태가 변경됐을 때 발생하는 이벤트입니다.{"eventType": "PAYMENT_STATUS_CHANGED","createdAt": "2022-01-01T00:00:00.000","data": {"paymentKey": "","status": "DONE","orderId": ""}}JSONpaymentKey
: 결제 건에 대한 고유한 키 값입니다.status
: 결제 상태입니다.READY
- 준비됨IN_PROGRESS
- 진행중WAITING_FOR_DEPOSIT
- 가상계좌 입금 대기 중DONE
- 결제 완료됨CANCELED
- 결제가 취소됨PARTIAL_CANCELED
- 결제가 부분 취소됨ABORTED
- 카드 자동 결제 혹은 키인 결제를 할 때 결제 승인에 실패함EXPIRED
- 유효 시간(30분)이 지나 거래가 취소됨
orderId
: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.
PAYOUT_STATUS_CHANGED
: 지급대행 상태가 변경됐을 때 발생하는 이벤트입니다.{"eventType": "PAYOUT_STATUS_CHANGED","createdAt": "2022-01-01T00:00:00.000","data": {"paymentKey": "","status": "COMPLETED","orderId": ""}}JSONpaymentKey
: 결제 건에 대한 고유한 키 값입니다.status
: 지급대행 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.REQUESTED
- 지급 요청됨IN_PROGRESS
- 처리 중COMPLETED
- 지급 완료FAILED
- 지급 실패
orderId
: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.
결제 상태 변경과 관련된 부분은 일반 결제와 동일합니다.
METHOD_UPDATE
: 고객의 결제수단이 등록/변경/삭제됐을 때 발생하는 이벤트입니다.{"eventType": "METHOD_UPDATE","createdAt": "2022-05-12T00:00:00.000","data": {"customerKey": "","methodKey": "","status": "ENABLE"}}JSONcustomerKey
: 가맹점에서 만든 고객의 고유 ID입니다.methodKey
: 결제 수단을 특정하는 키입니다.status
: 결제 수단 활성화 여부를 나타냅니다.ENABLED
: 결제 수단이 등록되어 사용할 수 있는 상태DISABLED
: 결제 수단이 삭제되어 사용할 수 없는 상태
CUSTOMER_STATUS_CHANGED
: 브랜드페이 고객의 상태 변경이 일어났을 때 발생하는 이벤트입니다.{"eventType": "CUSTOMER_STATUS_CHANGED","createdAt": "2022-01-01T00:00:00.000","data": {"customerKey": "","status": "PASSWORD_CHANGED","changedAt": "2022-01-01T00:00:00.000"}}JSONcustomerKey
: 가맹점에서 만든 고객의 고유 ID입니다.status
: 고객의 브랜드페이 사용 관련 상태입니다.CREATED
간편결제 가입REMOVED
간편결제 탈퇴PASSWORD_CHANGED
비밀번호 변경ONE_TOUCH_ACTIVATED
원터치결제 활성화ONE_TOUCH_DEACTIVATED
원터치결제 비활성화
changedAt
: 변경이 일어난 시점입니다. ISO 8601 형식인yyyy-MM-dd'T'HH:mm:ss.SSS
를 사용합니다.
가상계좌로 결제한 고객이 금액을 입금하거나 입금을 취소하면 토스페이먼츠에서 등록된 가상계좌 웹훅 URL을 호출합니다.
가상계좌 웹훅 이벤트 본문은 아래와 같은 형태입니다. 일반 웹훅 이벤트 타입에 속하지 않고 가상계좌에만 사용되는 웹훅으로 eventType
이 따로 없습니다.
{
"createdAt": "2022-01-01T00:00:00.000",
"secret": "",
"status": "DONE",
"orderId": ""
}
secret
: 가상계좌 웹훅 요청이 정상적인 요청인지 검증하기 위한 값입니다. 이 값이 결제 승인 API의 응답으로 돌아온secret
과 같으면 정상적인 요청입니다.status
: 입금 처리 상태입니다. 고객이 가상계좌에 입금하면 값이DONE
입니다. 입금이 취소되면 값이CANCELED
입니다.DONE
: 가상계좌에 입금 되었습니다.CANCELED
: 가상계좌 입금이 취소되었습니다.PARTIAL_CANCELED
: 가상계좌 입금 부분 취소가 이루어졌습니다.
orderId
: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.
테스트 환경에서 발급된 가상계좌로는 입금할 수 없습니다. 대신 입금을 한 것처럼 동작하는 입금・취소 이벤트를 제공합니다. 더 자세한 내용은 테스트 환경에서 확인해보세요.
가상계좌 웹훅 이벤트의 status
가 입금 완료 상태를 나타내는 DONE
으로 돌아온 뒤 CANCELED
혹은 WAITING_FOR_DEPOSIT
로 변경되어 재전송되는 경우가 있습니다. 고객 계좌 송금 한도가 초과되었거나 네트워크 이슈 등으로 입금이 취소되어 발생하는 상태 변경으로, 고객이 다시 입금해야 정상적으로 처리할 수 있습니다.
따라서 상태가 변경되어 돌아온 경우에는 첫 번째 콜백의 상태 확인 후 결제 완료 처리한 것을 되돌린 뒤 재입금이 되었는지 확인하고 다시 진행해야 합니다.
버전 2022-06-08부터 재입금이 필요한 상태가 달라졌습니다. 아래 내용을 통해 자세히 확인해보세요.
버전 1.4까지는 같은 주문에 대한 웹훅 이벤트의 상태가 DONE
에서 CANCELED
로 변경되어 다시 전송되면 재입금이 되어야 합니다.
{
"secret": "",
"status": "DONE",
"orderId": ""
}
{
"secret": "",
"status": "CANCELED",
"orderId": ""
}
버전 2022-06-08부터는 같은 주문에 대한 웹훅 이벤트의 상태가 아래와 같이 DONE
에서 WAITING_FOR_DEPOSIT
로 변경되어 다시 전송되었다면 재입금이 되어야 합니다.
재입금은 WAITING_FOR_DEPOSIT
상태에서만 할 수 있으니 유의하세요. 이전 버전과 달리 CANCELED
상태는 결제 취소 API 요청을 통해 결제가 취소되었을 때만 돌아옵니다.
{
"secret": "",
"status": "DONE",
"orderId": ""
}
{
"secret": "",
"status": "WAITING_FOR_DEPOSIT",
"orderId": ""
}