콘텐츠로 이동

웹훅 연동과 검증 (Webhooks)

결제 연동에서 웹훅은 결제 상태 변화(승인·실패·취소…)를 가맹점 서버에 비동기로 알리는 채널입니다. 토스페이먼츠(Toss Payments)는 PAYMENT_STATUS_CHANGED 같은 이벤트를 발행하고, 특정 주소로 HTTP 요청을 보냅니다. 이 장은 연동 흐름과 서명 검증의 중요성을 정리합니다.

이벤트 형태

토스 웹훅 이벤트 payload 예:

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2022-01-01T00:00:00.000000",
  "data": {
    "mId": "tosspayments",
    "paymentKey": "Fo6tDxffE9xBOcD6EQoTi",
    "orderId": "CoWWzNrTWTpFz16tTsYWs",
    "status": "DONE",
    "amount": 10000
  }
}
  • eventType 으로 어떤 변화인지, data 로 결제 정보를 담습니다.
  • 결제 승인은 보통 클라이언트 결제 + 서버에서 승인 API 호출(비동기 확인)로 완료되며, 웹훅은 상태 변경을 다시 알려 서버 상태를 동기화합니다.

서명 검증이 필수인 이유

웹훅 URL 이 외부에 노출되면 위조 요청을 받을 수 있습니다(예: 가짜 "결제 완료"). 그래서:

  • 웹훅 요청의 서명(HMAC-SHA-256 또는 공급자 지정 서명)을 반드시 검증합니다.
  • 검증에 실패하면 그 요청을 무시하고 결제 상태를 갱신하지 않아야 합니다.
  • 이를 놓치면 "결제는 승인됐지만 주문이 영원히 pending" 같은 조용한 실패가 발생해 심각한 고객 피해로 이어질 수 있습니다.

데이터스케쳐스 실무 관점

  • 웹빌더·이벤트 결제: D-SKET 웹빌더/이벤트에서 결제 상태를 신뢰하려면 웹훅 검증 + 주문 상태 머신(주문 DB 와 결제 상태 동기화)을 설계해야 합니다. 웹훅 실패 시 재전송(retry)과 멱등 처리(idempotency)도 함께 고려합니다.
  • 결제 금액·orderId 가 payload 와 서버 주문 내역과 일치하는지도 검증하는 것이 안전한 연동의 핵심입니다.

확인 필요

  • 웹훅 서명 방식·재전송 정책·결제 확인 API 흐름은 공급자 문서 버전에 따라 다르므로, 토스페이먼츠 개발자센터 최신 문서를 재확인하세요. (확인 필요)

더 알아보기