웹훅(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": "",
    "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": ""
    }
  }
  

  JSON복사하기
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • 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": ""
    }
  }
  

  JSON복사하기
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • 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"
    }
  }
  

  JSON복사하기
  • customerKey: 가맹점에서 만든 고객의 고유 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"
    }
  }
  

  JSON복사하기
  • customerKey: 가맹점에서 만든 고객의 고유 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": ""
}