웹훅을 잃지 않는 연동 설계: 서명 검증·멱등성·재처리

웹훅은 외부 시스템이 우리 서버로 보내는 HTTP 요청이지만, 일반적인 폼 제출처럼 한 번 도착하고 끝나는 메시지로 보면 위험합니다. 네트워크 오류로 재전송될 수 있고, 생성 순서와 다른 순서로 도착할 수 있으며, 같은 이벤트가 여러 번 처리될 수 있습니다.

안전한 웹훅 처리는 네 단계로 나눌 수 있습니다. 신뢰 경계에서 서명을 확인하고, 이벤트를 중복 없이 저장하고, 빠르게 수신 성공을 응답한 뒤, 업무 처리는 재시도 가능한 작업으로 분리합니다. 마지막으로 실패한 이벤트를 운영자가 찾아 선택적으로 복구할 수 있게 합니다.

1. 파싱하기 전에 원문 서명을 검증하기

웹훅의 발신자를 확인하는 코드는 애플리케이션의 신뢰 경계에 있습니다. 제공자가 서명 헤더와 엔드포인트 비밀을 사용하는 경우, 프레임워크가 JSON을 파싱하거나 공백을 바꾸기 전에 원문 요청 본문으로 서명을 검증해야 합니다. 서명이 틀리거나 필수 헤더가 없으면 업무 로직을 실행하지 않고 거부합니다.

서명 검증이 통과해도 오래된 유효 요청을 다시 보내는 재전송 공격을 막아야 합니다. 서명에 포함된 시각의 허용 범위를 확인하고, 서버 시계를 동기화하며, 이미 처리한 이벤트 ID를 다시 실행하지 않습니다. 비밀은 코드나 로그에 넣지 않고 제공자의 환경별·엔드포인트별 키 교체 절차를 준비합니다.

2. 수신과 업무 처리를 분리하기

웹훅 제공자는 수신 서버의 응답을 보고 재전송 여부를 판단할 수 있습니다. 따라서 수신 엔드포인트에서 결제 반영, 이메일 발송, 외부 API 호출 같은 긴 작업을 모두 수행하지 않습니다. 서명과 기본 형식을 확인한 이벤트를 먼저 저장하고, 처리할 작업을 큐에 넘긴 뒤 성공 응답을 반환합니다.

1. 원문 검증과 기본 필드 검사를 수행합니다.

2. 이벤트 ID·종류·발생 시각·스키마 버전을 저장합니다.

3. 같은 이벤트가 이미 접수됐는지 원자적으로 확인합니다.

4. 새 이벤트만 처리 큐에 넣고 수신 결과를 빠르게 응답합니다.

3. 이벤트 ID만 믿지 말고 업무 결과를 멱등하게 만들기

이벤트 ID를 저장하는 것은 중복 이벤트를 찾는 출발점입니다. 실제 업무 효과도 한 번만 발생해야 합니다. 예를 들어 동일한 결제 완료 이벤트가 다시 들어와도 주문을 두 번 완료하거나 이메일을 두 번 보내지 않도록 주문 상태와 처리 기록을 함께 검사합니다.

멱등 키의 범위와 보관 기간을 정하고, 같은 키에 다른 본문이 들어오면 충돌로 처리합니다. 처리 중인 이벤트와 완료된 이벤트를 구분해야 동시 요청 두 개가 모두 ‘아직 없음’을 보고 실행하는 경쟁 조건도 막을 수 있습니다.

• 이벤트 ID와 대상 리소스에 중복 방지 제약을 둡니다.

• 처리 중·성공·실패·수동 보류 상태를 구분합니다.

• 이미 성공한 이벤트는 동일한 결과를 반환하고 효과를 다시 실행하지 않습니다.

• 순서가 보장되지 않는 이벤트는 최신 객체를 다시 조회해 상태를 확인합니다.

4. 재시도와 격리를 운영 절차로 만들기

일시적인 네트워크 오류와 잘못된 데이터는 같은 방식으로 재시도하면 안 됩니다. 일시 오류에는 제한된 횟수와 간격의 재시도를 적용하고, 형식 오류·권한 오류·존재하지 않는 대상은 빠르게 격리해 사람이 판단하게 합니다. 무제한 재시도는 장애를 다른 시스템으로 증폭시킵니다.

반복 실패한 이벤트를 데드 레터 큐나 별도 실패 저장소에 모으면 원인 분석과 선택적 재처리가 가능합니다. 격리된 이벤트에는 마지막 오류, 시도 횟수, 원본 참조, 현재 대상 상태를 함께 남깁니다. 순서가 중요한 이벤트는 하나를 격리할 때 뒤의 이벤트를 계속 처리해도 되는지 먼저 확인해야 합니다.

웹훅 운영에서 반드시 볼 지표

수신 성공률만 보면 저장 후 처리 실패를 놓칩니다. 수신 응답 시간, 서명 검증 거부 건수, 중복 비율, 큐 대기 시간, 처리 성공률, 재시도 횟수, 실패 저장소의 오래된 이벤트 수를 분리해 봅니다. 각 지표에는 담당자와 대응 기한을 연결합니다.

• 서명 실패가 갑자기 늘면 비밀 교체나 공격 가능성을 조사합니다.

• 수신은 성공하지만 처리 지연이 늘면 큐와 소비자를 확인합니다.

• 중복 비율이 오르면 제공자 재전송과 응답 지연을 함께 봅니다.

• 실패 저장소에 이벤트가 쌓이면 원인 분류 후 한 건으로 재처리합니다.

완료 조건은 모의 재전송으로 확인하기

웹훅 구현이 끝났다는 기준은 정상 이벤트 하나가 처리된 사실이 아닙니다. 같은 이벤트를 여러 번 보내고, 순서를 바꾸고, 처리 중 네트워크를 끊고, 서명과 시각을 틀리고, 소비자를 멈춘 뒤 다시 시작해 봅니다. 모든 경우에 중복 효과가 없고, 실패한 이벤트를 찾고, 안전한 상태로 복구할 수 있어야 합니다.

웹훅을 HTTP 콜백이 아니라 신뢰할 수 없는 네트워크를 건너오는 이벤트로 취급하면 설계의 우선순위가 분명해집니다. 검증, 저장, 빠른 응답, 멱등 처리, 제한된 재시도, 선택적 복구를 한 흐름으로 묶어야 외부 시스템의 재전송이 우리 서비스의 중복 과금과 누락으로 이어지지 않습니다.