Toss Webhook

웹훅은 데이터가 변경되었을 때 상점 서버에서 실시간으로 알림을 받을 수 있는 기능입니다.
알림을 받을 웹훅 URL을 만들고 등록해두면 결제 상태가 변경되었을 때, 요청해 둔 지급대행이 실행됐을 때, 브랜드페이에 고객이 결제 수단을 업데이트 했을 때와 같은 변경 사항을 알 수 있습니다.

웹훅 알림 사용하기

1. 웹훅을 이용해서 알림을 받고 싶은 이벤트 타입과 데이터 형식을 확인합니다.
2. 웹훅 URL을 만든 뒤 개발자센터의 웹훅 페이지에서 등록합니다.
3. 고객이 입금하거나 결제를 취소하는 등 상태 변경이 발생합니다.
4. 등록해 둔 웹훅 URL로 전달받은 이벤트를 확인합니다.

웹훅 재전송 정책

등록한 웹훅 URL에 웹훅 전송 후 응답으로 HTTP 200 OK이 돌아오지 않으면 전송 실패로 판단합니다. 최초의 웹훅 전송이 실패하면 성공할 때까지 최대 7회(최초 전송으로부터 3일 19시간 후)까지 웹훅을 재전송합니다.
재전송 간격은 1분 → 4분 → 16분 → 64분 → 256분 → 1024분 → 4096분으로 늘어납니다.

마지막 재전송까지 실패하면 이메일로 전송에 실패한 이벤트 정보를 알려드립니다. 이메일에 포함된 웹훅 이벤트 정보를 확인하고 상점 서버나 웹훅 URL에 이상이 있는지 점검해보세요.

전달받은 이벤트 확인하기

웹훅은 HTTP POST 메서드를 사용해서 JSON 형태로 전달됩니다. 서버에서 JSON을 처리할 수 있는지 확인해주세요. HTTP도 지원하지만 보안을 위해 HTTPS로 통신하는 것을 권장합니다.
데이터가 변경되면 웹훅 이벤트가 발생합니다. 등록해 둔 웹훅 URL로 돌아오는 웹훅 이벤트 본문은 아래와 같은 형태입니다.

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2022-05-12T00:00:00.000",
  "data": {
    "paymentKey": "B3EvL1cKz9p-kO6XPNpfF",
    "status": "DONE",
    "orderId": "YOWWcpZSDCZ8WJC5x7mkl"
  }
}

아래 필드들은 공통입니다.

• 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": "B3EvL1cKz9p-kO6XPNpfF",
    "status": "DONE",
    "orderId": "YOWWcpZSDCZ8WJC5x7mkl"
  }
}

• data 객체에는 아래와 같은 정보가 담깁니다.
• paymentKey: 결제 건에 대한 고유한 키 값입니다.
• status: 결제 상태입니다.
• READY - 준비됨
• IN_PROGRESS - 진행중
• WAITING_FOR_DEPOSIT - 가상계좌 입금 대기 중
• DONE - 결제 완료됨
• CANCELED - 결제가 취소됨
• PARTIAL_CANCELED - 결제가 부분 취소됨
• ABORTED - 카드 자동 결제 혹은 키인 결제를 할 때 결제 승인에 실패함
• EXPIRED - 유효 시간(30분)이 지나 거래가 취소됨
• orderId: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.

ref

• 웹훅(Webhook) 연동하기 | 토스페이먼츠 결제 연동 문서