웹훅(Webhook) 연결하기

웹훅은 데이터가 변경되었을 때 상점 서버에서 실시간으로 알림을 받을 수 있는 기능입니다. 웹훅을 연동해서 결제 상태 변경, 지급대행 실행, 브랜드페이 고객 결제수단 업데이트와 같은 변경 사항을 실시간으로 받아보세요.

웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다. 웹훅 본문과 자세한 설명은 각 이벤트 타입을 선택해서 살펴보세요.

개발자센터 웹훅 페이지에서 웹훅 등록하기를 누르면 웹훅 이벤트 등록 팝업창이 열립니다. 웹훅 이름, 웹훅 URL을 입력하고 등록할 이벤트를 선택하세요. 마지막으로 '등록하기' 를 누르면 웹훅이 등록됩니다.

웹훅 목록에서 잘 등록되었는지 확인하세요. 결제 상태가 변경되어 등록한 이벤트가 발생하면 웹훅 URL로 웹훅 이벤트가 전송됩니다. 웹훅은 상세 페이지에서 삭제할 수 있습니다.

개발자센터 웹훅 목록에서 등록한 웹훅을 선택하면 웹훅 상세 정보와 전송 기록을 확인할 수 있습니다.

웹훅 전송 기록은 등록한 이벤트의 가장 최근 전송 상태를 보여줍니다. 즉, 하나의 전송 기록은 이벤트가 발생한 뒤의 상태 변화를 표현합니다. 이벤트 발생 시간을 선택하면 해당 이벤트의 본문을 볼 수 있습니다.

전송 상태는 '전송 중', '성공', '실패' 중 하나입니다.

웹훅 전송 후 응답으로 HTTP 2xx 코드가 돌아오면 전송 상태는 '성공'입니다. 최초의 웹훅 전송이 실패하면 최대 7회(최초 전송으로부터 3일 19시간 후)까지 웹훅을 재전송합니다.

1회부터 6회까지 웹훅 전송이 실패해도 웹훅 상태는 '전송 중'입니다. 7회 웹훅 전송이 실패하면 웹훅 상태가 '실패'로 변경됩니다.

카드, 계좌이체, 휴대폰, 상품권 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.

결제창이 유효한 30분 안에 고객이 결제창에서 인증을 하지 않거나, 고객의 결제 인증이 유효한 10분 안에 상점에서 결제 승인 API를 호출하지 않으면 결제 상태가 EXPIRED로 변경됩니다.

고객이 결제창을 닫으면 결제 상태가 바뀌지 않기 때문에 웹훅도 전송되지 않습니다.

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2022-01-01T00:00:00.000000",
  "data": {
    "mId": "tosspayments",
    "version": "2022-11-16",
    "lastTransactionKey": "B7103F204998813B889C77C043D09502",
    "paymentKey": "",
    "orderId": "",
    "status": "DONE",
    "requestedAt": "2022-08-05T12:56:00+09:00",
    "approvedAt": "2022-08-05T12:56:21+09:00",
    "useEscrow": false,
    "card": {
      "issuerCode": "61",
      "acquirerCode": "31",
      "number": "48902300****406*",
      "installmentPlanMonths": 0,
      "amount": 10000
      //...
    }
    //...
  }
}

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  상태가 변경된 Payment 객체입니다.

가상계좌 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.

가상계좌 웹훅 연동 예제, 입금 테스트하는 방법 등 더 자세한 연동 방법은 가상계좌 웹훅 연동 가이드를 참고하세요.

다른 웹훅 이벤트 본문과 달리 eventType, data가 없습니다. 결제 정보를 보고 싶다면 orderId로 결제 조회를 하세요.

{
  "createdAt": "2022-01-01T00:00:00.000000",
  "secret": "",
  "status": "DONE",
  "transactionKey": "9FF15E1A29D0E77C218F57262BFA4986",
  "orderId": ""
}

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• secret 필수 · string
  

  가상계좌 웹훅 요청이 정상적인 요청인지 검증하는 값입니다. 결제 승인 API의 응답으로 돌아온 secret과 같으면 정상적인 요청입니다.

• status 필수 · string
  

  결제 상태입니다.

• transactionKey 필수 · string
  

  상태가 변경된 가상계좌 거래를 특정하는 키입니다.

• orderId 필수 · string
  

  주문번호입니다.

지급대행 요청 상태가 COMPLETED, FAILED로 변경되면 웹훅이 전송됩니다. 자세한 상태 설명은 status에서 확인하세요.

{
  "eventType": "PAYOUT_STATUS_CHANGED",
  "createdAt": "2022-01-01T00:00:00.000000",
  "data": {
    "payoutKey": "",
    "subMallId": "testmall100",
    "payoutDate": "20220103",
    "payoutAmount": 10000,
    "requestedAt": "20220101100130",
    "account": {
      "bankCode": "03",
      "accountNumber": "00123412341234",
      "holderName": null
    },
    "status": "COMPLETED",
    "metadata": null,
    "failure": null,
    "transferSummary": null
  }
}

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  상태가 변경된 Payout 객체입니다.

브랜드페이 고객의 결제수단이 변경되면 웹훅이 전송됩니다.

{
  "eventType": "METHOD_UPDATED",
  "createdAt": "2022-05-12T00:00:00.000000",
  "data": {
    "customerKey": "",
    "methodKey": "",
    "status": "ENABLE"
  }
}

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  아래 세 가지 필드가 돌아옵니다.

  • customerKey: 상점에서 만든 고객의 고유 ID입니다.
  • methodKey: 결제수단을 특정하는 키입니다.
  • status: 결제수단의 상태입니다.
    • ENABLED: 결제수단이 등록되어 사용할 수 있게 된 상태
    • DISABLED: 결제수단이 삭제되어 사용할 수 없게 된 상태
    • ALIAS_UPDATED: 등록되어 있는 결제수단의 별명이 변경된 상태

브랜드페이 고객의 상태가 변경되면 웹훅이 전송됩니다.

{
  "eventType": "CUSTOMER_STATUS_CHANGED",
  "createdAt": "2022-01-01T00:00:00.000000",
  "data": {
    "customerKey": "",
    "status": "PASSWORD_CHANGED",
    "changedAt": "2022-01-01T00:00:00+09:00"
  }
}

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  아래 세 가지 필드가 돌아옵니다.

  • customerKey: 상점에서 만든 고객의 고유 ID입니다.
  • status: 고객의 브랜드페이 사용 관련 상태입니다.
    • CREATED: 간편결제에 가입한 상태
    • REMOVED: 간편결제에 탈퇴한 상태
    • PASSWORD_CHANGED: 비밀번호를 변경한 상태
    • ONE_TOUCH_ACTIVATED: 원터치결제를 활성화한 상태
    • ONE_TOUCH_DEACTIVATED: 원터치결제를 비활성화한 상태
  • changedAt: 변경이 일어난 시점입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.