APP DEVELOPMENT TERM
웹훅
이벤트가 생겼을 때 보내는 서버 알림
웹훅은 결제 완료나 배송 변경처럼 약속한 이벤트가 생겼을 때 외부 서비스가 우리 서버의 정해진 주소로 데이터를 보내 알려주는 방식입니다.
30초 이해
웹훅은 우리 서버가 계속 물어보는 대신 중요한 변화가 생긴 순간 외부 서비스가 먼저 알려주는 연결 방식입니다
결제 결과를 확인하기 위해 서버가 매분 결제사에 상태를 묻는 방식도 있지만 불필요한 요청이 많고 늦게 알 수 있습니다. 웹훅을 등록하면 결제 완료·취소 같은 이벤트가 생겼을 때 결제사가 약속한 주소로 결과를 보냅니다.
웹훅은 한 번만, 항상 순서대로, 즉시 도착한다고 가정하면 안 됩니다. 발신 확인, 중복 이벤트 처리, 재시도, 늦거나 순서가 바뀐 이벤트, 처리 기록과 실패 알림을 함께 설계해야 운영에서 안전합니다.
한 장으로 이해
외부 서비스 이벤트가 웹훅으로 반영되는 과정
이벤트가 생기면 등록된 주소로 알림을 보내고 우리 서버가 발신과 중복을 확인한 뒤 상태를 반영합니다.
- 01
이벤트 발생
결제 완료·취소·배송 변경 같은 상태 변화가 생깁니다.
- 02
웹훅 전송
외부 서비스가 등록된 HTTPS 주소로 이벤트를 보냅니다.
- 03
검증·중복 확인
서명과 이벤트 식별자를 확인하고 이미 처리했는지 봅니다.
- 04
상태 반영
데이터를 한 번만 바꾸고 결과·실패 기록을 남깁니다.
웹훅은 빠른 알림 통로이지만 중요한 상태는 발신 검증과 중복 방지, 필요시 원본 API 재확인으로 보호해야 합니다.
언제 사용하는 개념인가요?
결제 결과를 받을 때
앱이 닫혀 있어도 결제 완료·취소·환불 상태를 서버에 반영합니다.
외부 업무 변화를 연결할 때
배송, 예약, 회원, 전자서명이나 문서 처리 상태가 바뀌면 후속 작업을 시작합니다.
자동 알림·동기화를 만들 때
특정 이벤트 뒤 메시지를 보내거나 내부 데이터와 다른 시스템을 맞춥니다.
왜 중요한가요?
변화를 더 빠르고 효율적으로 받습니다
상태를 반복 조회하는 대신 필요한 이벤트가 생겼을 때만 알림을 받을 수 있습니다.
중요 상태를 서버에서 이어갑니다
사용자가 앱을 닫거나 화면 응답을 놓쳐도 결제·배송 같은 결과를 반영할 수 있습니다.
중복과 위조를 별도로 막아야 합니다
서명, 이벤트 식별자와 처리 기록 없이는 같은 알림이나 거짓 요청이 상태를 잘못 바꿀 수 있습니다.
실제 상황 예시
클래스 결제 완료 웹훅을 받는다면
결제사가 보낸 이벤트를 그대로 믿지 않고 검증과 재처리 가능한 기록을 거칩니다.
수신할 때 확인할 흐름
- HTTPS 수신 주소 운영
- 결제사 서명·발신 검증
- 결제 번호·금액·상태 확인
- 같은 이벤트의 중복 처리 방지
장애 때 이어갈 운영
- 처리 실패 로그와 알림
- 재시도 횟수와 지연 대응
- 순서가 바뀐 취소·완료 이벤트
- 결제사 API로 최종 상태 재확인
웹훅 수신에 성공 응답을 줬는지뿐 아니라 실제 주문 상태가 정확히 한 번 반영됐는지 추적할 수 있어야 합니다.
자주 하는 오해
“웹훅은 일반 알림 푸시다”
사용자 휴대폰 알림과 달리 서비스 서버가 다른 서버의 주소로 이벤트 데이터를 보내는 연결 방식입니다.
“웹훅은 항상 한 번만 온다”
전송 실패나 재시도로 같은 이벤트가 여러 번 올 수 있어 식별자와 처리 기록으로 중복을 막아야 합니다.
“웹훅을 받으면 내용을 그대로 믿어도 된다”
제공사가 안내한 서명 검증과 HTTPS를 적용하고 중요한 상태는 원본 API로 다시 확인할 수 있어야 합니다.
우리 서비스에 적용할 때 확인하세요
- 1수신 주소가 HTTPS이며 외부에서 안정적으로 접근되나요?
- 2제공사가 안내한 서명이나 비밀값으로 발신을 검증하나요?
- 3같은 이벤트가 다시 와도 상태를 한 번만 바꾸나요?
- 4순서가 바뀌거나 늦게 온 이벤트를 안전하게 처리하나요?
- 5실패·재시도·최종 처리 결과를 조회하고 알림받을 수 있나요?
공식 참고
서비스 기준은 공식 문서에서 다시 확인하세요
다음 자료
이해한 내용을 바로 적용해보세요
요청·응답의 상위 개념인 API, 웹훅 수신 주소를 구성하는 REST API와 중복·재시도 대응을 이어서 확인하세요.
웹훅은 수신 성공보다 검증·중복 방지·복구 기록이 중요합니다
중요한 이벤트가 빠지거나 두 번 반영되지 않도록 운영 흐름까지 함께 확인하세요.