토스페이먼츠 웹훅 등록하는 방법

1. 마이페이지에서 웹훅 URL 복사하기#

마이페이지 → 카드결제설정에서 토스페이먼츠를 선택하고 결제용 키를 먼저 저장합니다. 카드결제 사용을 켜고 테스트 모드를 끈 상태에서 본인 운영 키가 저장되면 표시되는 결제통보 웹훅 URL 옆의 ‘복사’를 누르세요. 테스트 기본 키에서 판매자 키로 변경하면 URL이 달라질 수 있으므로 현재 화면의 주소를 사용합니다.

2. 개발자센터에서 웹훅 등록 열기#

토스페이먼츠 상점관리자에서 개발자센터로 이동한 뒤, 왼쪽 웹훅 메뉴를 누릅니다. 결제용 키와 동일한 상점 및 환경(테스트·라이브)을 선택하고 + 웹훅 등록을 누르세요.

3. URL과 이벤트 입력하기#

1. 상점아이디(MID)
   실제 결제에 사용하는 판매자 상점을 선택합니다.
2. 이름
   LiveChatOrder 결제 알림 등 알아보기 쉬운 이름을 입력합니다. 스크린샷처럼 webhook으로 입력해도 됩니다.
3. URL
   마이페이지에서 복사한 결제통보 웹훅 URL을 그대로 붙여 넣습니다.
4. 구독할 이벤트
   현재 국내 카드결제 연동에서는 PAYMENT_STATUS_CHANGED를 선택합니다.
5. 등록
   ‘등록’을 누른 뒤 목록에서 MID, URL, 구독 이벤트를 확인합니다.

어떤 이벤트를 선택하나요?#

• PAYMENT_STATUS_CHANGED — 선택: 현재 카드결제의 상태 변경 알림입니다.
• DEPOSIT_CALLBACK — 현재 불필요: 토스 가상계좌의 입금·입금 취소 알림입니다. 판매자 일반 계좌로 받는 무통장입금 알림은 아닙니다.
• CANCEL_STATUS_CHANGED — 현재 불필요: 비동기 방식으로 승인되는 해외 간편결제의 취소 결과 알림입니다. 국내 카드결제 취소를 위해 추가로 선택할 필요는 없습니다.
• 그 외 이벤트 — 현재 불필요: 브랜드페이, 지급대행 등 별도 서비스용입니다.

이 웹훅은 결제 상태 확인용입니다. 현금영수증용 키 등록이나 현금영수증 발급 결과 확인을 대신하지 않습니다.

등록 후 확인하기#

이 화면에서 복사한 운영 웹훅 URL은 해당 운영 상점에 등록하세요. 기본 테스트 모드에서는 웹훅 URL이 표시되지 않습니다. 결제 상태 변경 후 개발자센터의 웹훅 전송 기록에서 성공 여부를 확인하고, LiveChatOrder 결제내역의 처리 결과도 확인합니다. 전송 실패 시 등록한 URL, MID, 테스트·라이브 환경을 다시 확인하세요. 웹훅 등록만으로 PG 계약이나 현금영수증 사용 설정이 완료되는 것은 아닙니다.

토스페이먼츠 공식 웹훅 이벤트 안내 ↗