웹훅이란? API·폴링과의 차이

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

오늘의 인사이트 요약

• 웹훅은 사건이 발생한 시스템이 등록된 주소로 변경 사실을 보내는 방식입니다.

• 폴링은 받는 쪽이 API로 주기적으로 조회하므로 요청을 시작하는 주체가 다릅니다.

• 운영자는 웹훅 수신 여부와 업무 처리 결과를 나누고 중복·누락을 확인해야 합니다.

웹훅(Webhook)은 특정 사건이 발생했을 때 다른 시스템이 미리 등록한 주소로 데이터를 보내는 방식입니다. 우리 서비스가 주기적으로 변경 여부를 묻는 폴링과 달리, 사건이 생긴 쪽에서 먼저 알려줍니다. API를 완전히 대체하는 기술은 아니며 필요할 때 함께 사용합니다.

결제 상태 변경처럼 외부 서비스의 소식을 받아 내부 상태를 갱신할 때 웹훅을 활용할 수 있습니다. 오늘은 웹훅의 동작 방식과 API·폴링의 차이, 연동할 때 확인할 예외를 정리해 보겠습니다.

1. 웹훅은 어떻게 동작하나요?

받는 쪽에서 수신 주소와 받을 사건을 등록하면 웹훅을 사용할 준비가 됩니다. 이후 해당 사건이 생길 때 보내는 서비스가 등록된 주소로 요청을 보냅니다. 받는 서버는 요청을 확인하고 응답한 뒤, 전달받은 내용에 맞춰 내부 작업을 처리합니다. 여기서 사건은 결제 상태 변경이나 새 코드 등록처럼 시스템이 정의한 이벤트를 뜻합니다.

GitHub는 저장소에 코드가 올라오거나 풀 리퀘스트가 생성되는 등의 이벤트를 구독할 수 있습니다. 등록한 주소로 전달된 정보를 받아 테스트나 배포 등 다른 작업을 시작하는 방식입니다. 이벤트 구독과 REST API 조회의 차이를 더 알아보고 싶다면 GitHub의 웹훅 소개를 참고해 보세요.

브라우저를 닫아도 서버는 받을 수 있나요?

수신 서버가 정상적으로 동작한다면 사용자가 브라우저를 닫아도 웹훅을 받을 수 있습니다. 서버 사이에서 요청을 주고받기 때문입니다. 다만 웹훅이 도착했다고 사용자 화면까지 저절로 바뀌는 것은 아닙니다. 화면이 새 상태를 가져오는 방식은 별도로 구현합니다.

국내에서는 토스페이먼츠가 결제 상태 변경 등의 이벤트를 제공합니다. 가상계좌 입금처럼 처음 요청한 시점 이후에 상태가 달라지는 업무에서 변경을 전달받는 용도입니다. 모든 사건을 보내주는 것은 아니므로, 필요한 이벤트가 실제로 제공되는지부터 확인해야 합니다.

2. API·폴링과 무엇이 다른가요?

API는 시스템끼리 기능과 데이터를 주고받도록 정한 인터페이스입니다. 폴링은 그 API를 일정 간격으로 호출해 변화를 확인하는 사용 방식이고, 웹훅은 사건이 생겼을 때 보내는 쪽에서 요청하는 방식입니다. 따라서 웹훅과 API를 서로 대체해야 하는 제품처럼 비교하면 혼동하기 쉽습니다.

예를 들어 주문 상태를 확인하는 상황을 생각해 보겠습니다. 폴링은 우리 서버가 외부 시스템에 상태를 반복해서 묻습니다. 반면 웹훅은 외부 시스템이 상태 변경을 알려줍니다. 변경이 없는 동안에도 조회가 필요한지, 변경 후 얼마나 빨리 알아야 하는지에 따라 적합한 방식을 고를 수 있습니다.

웹훅과 API를 함께 쓰는 경우

웹훅에 변경된 항목의 식별자만 담겼다면 API로 상세 내용을 다시 조회할 수 있습니다. 이벤트를 받은 시점보다 상태가 더 바뀌었을 가능성이 있을 때도 최신 정보 조회를 함께 설계합니다. 알림을 받는 것과 현재 상태를 읽는 것은 역할이 다릅니다.

아래 비교에서 API 조회는 필요한 시점에 한 번 요청하는 경우를 뜻합니다. 폴링도 API를 사용하므로 표의 세 항목을 독립된 기술 분류로 해석할 필요는 없습니다.

3. 중복이나 누락은 어떻게 처리하나요?

수신 성공과 업무 처리 완료는 구분합니다. 웹훅에 응답했어도 이후 주문 갱신 작업이 실패할 수 있기 때문입니다. 시간이 오래 걸리는 작업은 안전하게 저장한 작업 목록에 넘기고, 수신 기록과 처리 결과를 따로 남기는 방식을 검토할 수 있습니다. 응답을 보내기 전에 작업이 안전하게 저장됐는지 확인하면 처리할 일이 사라지는 문제를 줄일 수 있습니다.

재전송 정책은 제공사마다 다릅니다. 토스페이먼츠는 웹훅을 받으면 10초 이내에 200 응답을 보내도록 안내하며, 실패하면 최대 7회 재전송합니다. 이 숫자를 다른 서비스에도 그대로 적용해서는 안 됩니다. 등록 방법과 실제 재전송 간격은 토스페이먼츠 웹훅 연결 가이드에서 함께 살펴보실 수 있습니다.

같은 사건이 두 번 와도 결과는 한 번만 반영해야 합니다

Stripe는 같은 이벤트가 여러 번 도착할 수 있고 전달 순서를 보장하지 않는다고 설명합니다. 처리한 이벤트 식별자를 기록하고 현재 상태를 함께 확인하면 중복 요청으로 같은 업무를 반복하는 일을 줄일 수 있습니다. 발신자 확인에는 제공사의 서명 검증 방식도 적용합니다. 중복·순서 처리와 서명 검증의 구체적인 조건은 Stripe의 웹훅 운영 지침을 참고해 보세요.

연동 테스트에서는 정상 수신만 보지 말고 다음 예외 상황도 확인해 보세요. 제공사의 재전송이 끝난 뒤에도 상태가 맞지 않는다면 API 대조나 운영자 확인으로 복구할 방법이 있어야 합니다.

• 같은 이벤트를 다시 받았을 때 주문이나 알림이 중복 생성되지 않나요?

• 오래된 이벤트가 나중에 와도 현재 상태를 과거로 되돌리지 않나요?

• 발신자 검증에 실패한 요청은 내부 업무를 실행하지 않나요?

• 수신에는 성공했지만 내부 처리가 실패한 건을 찾아 재처리할 수 있나요?

서비스 연동을 운영까지 연결하려면

똑똑한개발자는 웹·앱과 관리자 시스템을 기획·개발·운영하며 기존 시스템의 연결 방식을 함께 검토합니다. 자체 서비스인 pluuug를 운영해 온 경험도 있습니다. 외부 상태를 받는 기능과 운영자가 실패한 작업을 확인할 화면을 함께 살피면, 연동 이후의 관리 범위를 정하는 데 도움이 됩니다.

외부 서비스와 연결했는데 주문이나 업무 상태가 맞지 않나요? 이벤트 수신과 처리·복구 흐름을 살펴보고 필요한 개발 범위를 함께 정리해 드리겠습니다. 감사합니다. :)

📚 이어서 읽어보세요

• 캐시란? 수정한 웹페이지가 그대로 보이는 이유

• 서비스 데이터 이전, 검수와 전환 기준 정하기