개발자가 알아야 할 지식: 웹훅, 이벤트를 밖으로 안전하게 내보내는 계약

웹훅은 “무언가 일어났으니 너도 알아야 한다”는 메시지를 외부 시스템에 보내는 방식입니다. 결제 완료, 구독 갱신, 파일 처리 완료, 배포 상태 변경처럼 상대 시스템이 즉시 반응해야 하는 일에 자주 쓰입니다.

왜 개발자가 알아야 하나

웹훅은 단순한 HTTP POST처럼 보이지만 실제로는 시스템 간 계약입니다. 보내는 쪽은 이벤트가 무엇인지, 언제 재시도하는지, 어떤 순서를 보장하는지 알려야 하고, 받는 쪽은 인증, 중복 처리, 장애 복구를 준비해야 합니다.

개발자가 웹훅을 알아야 하는 이유는 연동 장애가 조용히 쌓이기 쉽기 때문입니다. 한 번 실패한 결제 이벤트, 두 번 도착한 배송 이벤트, 순서가 뒤집힌 상태 변경 이벤트는 데이터 불일치로 이어집니다.

좋은 웹훅 설계는 외부 파트너에게 친절합니다. 문서화된 이벤트 타입, 검증 가능한 서명, 안정적인 재시도 정책, 테스트 도구가 있으면 연동 비용이 크게 줄어듭니다.

핵심 개념

첫 번째는 인증입니다. 웹훅 엔드포인트는 인터넷에 열려 있으므로 요청 본문과 타임스탬프를 공유 비밀키로 서명하고, 받는 쪽은 그 서명을 검증해야 합니다. 단순히 IP allowlist만 믿으면 운영 환경 변화에 약합니다.

두 번째는 멱등성입니다. 네트워크 오류 때문에 같은 이벤트가 여러 번 도착할 수 있습니다. 수신자는 이벤트 ID를 저장하고 이미 처리한 이벤트를 다시 처리하지 않아야 합니다.

세 번째는 재시도와 순서입니다. 대부분의 웹훅은 적어도 한 번 전달을 목표로 하며 정확히 한 번 전달을 보장하지 않습니다. 이벤트 순서도 항상 믿기 어렵기 때문에 현재 상태 조회 API와 함께 설계하는 편이 안전합니다.

작은 예시 또는 체크리스트

결제 서비스가 invoice.paid 웹훅을 보낸다고 합시다. 수신 서버가 500을 반환하면 발신자는 일정 시간 뒤 재시도합니다. 이때 수신자가 이벤트 ID를 기준으로 중복 처리를 하지 않으면 사용자의 구독 기간이 두 번 연장될 수 있습니다. 반대로 재시도 정책이 없다면 일시 장애 하나로 결제 완료 상태가 영원히 반영되지 않을 수 있습니다.

• 모든 웹훅 요청에 검증 가능한 서명과 타임스탬프가 포함되는가?
• 수신자가 이벤트 ID를 저장해 중복 처리를 막는가?
• 2xx와 비2xx 응답에 대한 재시도 정책이 문서화되어 있는가?
• 이벤트 스키마와 버전 변경 정책이 명확한가?
• 웹훅 실패를 운영자가 볼 수 있는 로그, 대시보드, 재전송 기능이 있는가?
• 웹훅만 믿지 않고 필요할 때 현재 상태를 다시 조회할 API가 있는가?

실무에서 자주 생기는 오해

• “POST 한 번 보내면 끝”이라는 오해가 있습니다. 웹훅은 네트워크, 인증, 중복, 재시도, 문서화가 모두 들어간 통합 계약입니다.

• “순서대로 올 것이다”라고 가정하는 것도 위험합니다. 서로 다른 큐나 재시도 경로를 거치면 생성 순서와 도착 순서가 달라질 수 있습니다.

• “서명 검증은 받는 쪽 책임”이라고만 보는 것도 부족합니다. 발신자는 안전하게 검증할 수 있는 서명 방식과 예제를 제공해야 합니다.

• “실패하면 파트너가 다시 보내겠지”라는 생각도 불친절합니다. 발신 쪽에는 실패 기록과 재전송 도구가 있어야 운영자가 문제를 복구할 수 있습니다.

오늘 바로 적용해보기

현재 운영 중인 웹훅 하나를 골라 같은 이벤트가 두 번 들어왔을 때 결과가 달라지는지 확인해보세요.

서명 검증 실패, 오래된 타임스탬프, 알 수 없는 이벤트 타입을 각각 어떻게 처리하는지 테스트를 추가하세요.

문서에는 예시 payload만 두지 말고 재시도 간격, timeout, 응답 코드 의미, 이벤트 버전 정책을 함께 적어두세요.

더 알아보기

• Stripe Docs: Webhooks
• GitHub Docs: Webhook events and payloads
• Svix: Webhook best practices

오늘의 takeaway

웹훅은 HTTP 요청 하나가 아니라, 실패와 중복을 전제로 만든 시스템 간 약속입니다.