웹훅 재시도 정책 설계법

웹훅은 결제 완료, 배송 상태, 외부 시스템 변경을 자동으로 전달하지만 실패했을 때 기준이 없으면 데이터가 어긋납니다. 무한 재시도는 상대 서버에 부담을 주고, 재시도가 없으면 중요한 이벤트를 놓칩니다. 웹훅 재시도 정책은 외부 연동을 신뢰 가능한 업무 흐름으로 만들기 위한 운영 기준입니다.

웹훅은 반드시 검증 후 처리한다

웹훅 엔드포인트가 외부에 열려 있다면 요청 출처를 확인해야 합니다. 서명 검증, 타임스탬프 확인, 허용 IP, 비밀키 회전 기준을 정하세요. 검증 없이 받은 이벤트를 처리하면 위조 요청으로 결제나 상태가 바뀔 수 있습니다.

검증 실패와 처리 실패는 구분해야 합니다. 검증 실패는 보안 이벤트로 기록하고 재시도하지 않을 수 있으며, 처리 실패는 일시 장애로 재시도 대상이 됩니다. 오류 유형이 섞이면 대응이 어려워집니다.

재시도 간격은 점진적으로 늘린다

웹훅 실패 후 즉시 반복 호출하면 장애 중인 시스템에 더 큰 부담을 줍니다. 1분, 5분, 30분, 2시간처럼 점진적으로 간격을 늘리는 백오프를 사용하세요. 최대 재시도 횟수와 최종 실패 처리 기준도 필요합니다.

이벤트 중요도에 따라 재시도 정책을 다르게 둘 수 있습니다. 결제 완료나 환불 이벤트는 강하게 보장해야 하고, 단순 알림 이벤트는 재시도 횟수를 줄일 수 있습니다. 모든 이벤트를 같은 정책으로 처리하면 비용과 위험이 맞지 않습니다.

중복 이벤트를 안전하게 처리한다

웹훅은 네트워크 문제로 같은 이벤트가 여러 번 도착할 수 있습니다. 이벤트 ID, 외부 거래 ID, 상태 버전을 기준으로 멱등 처리를 해야 합니다. 같은 결제 완료 이벤트가 두 번 왔다고 두 번 적립하거나 두 번 발송하면 안 됩니다.

처리 결과도 기록하세요. 이벤트 수신 시간, 검증 결과, 처리 상태, 재시도 횟수, 마지막 오류를 남기면 고객 문의와 장애 조사에 도움이 됩니다. 로그가 없으면 외부 시스템 탓인지 내부 처리 오류인지 알 수 없습니다.

실패 이벤트를 운영자가 볼 수 있게 한다

웹훅 실패가 로그에만 있으면 운영팀은 문제를 늦게 압니다. 실패율, 최종 실패 건수, 오래 대기 중인 이벤트를 대시보드나 알림으로 보여주세요. 고객 결제나 배송 상태에 영향을 주는 이벤트는 즉시 알림이 필요합니다.

최종 실패 이벤트는 수동 재처리 도구가 있어야 합니다. 개발자가 직접 DB를 수정하는 방식은 위험합니다. 권한 있는 운영자가 이벤트 내용을 확인하고 재처리하거나 무시할 수 있는 절차를 만드세요.

실행 체크리스트

• 웹훅 서명, 타임스탬프, 출처 검증 기준을 만들었습니다.
• 검증 실패와 처리 실패를 다른 오류 유형으로 기록합니다.
• 이벤트 중요도별 재시도 간격과 최대 횟수를 정했습니다.
• 이벤트 ID 기준 멱등 처리로 중복 반영을 막았습니다.
• 최종 실패 이벤트 알림과 수동 재처리 절차를 마련했습니다.

이 글은 정보보호와 서비스 안정성 자료, 디지털 서비스 정책 자료, 개인정보 처리 안전조치 자료의 공개 자료를 바탕으로, 작은 팀이 바로 점검하고 문서화할 수 있는 운영 절차로 재구성했습니다. 실제 적용 전에는 업종, 고객 유형, 계약 구조, 보관 중인 데이터와 사용하는 도구가 다른지 먼저 확인해야 합니다.

정책이나 체크리스트는 작성보다 적용이 더 어렵습니다. 최근 사례 하나를 골라 접수, 판단, 승인, 기록, 고객 안내까지 끝까지 통과시켜 보세요. 이 과정에서 담당자가 헷갈리는 표현, 빠진 승인자, 기록 위치가 드러납니다.

팀원이 늘어날수록 구두 합의는 빠르게 흔들립니다. 고객에게 설명할 문장, 내부 담당자가 확인할 표, 예외를 승인할 기준을 같은 문서 안에 두면 담당자가 바뀌어도 품질을 유지할 수 있습니다. 특히 고객 돈, 개인정보, 계약 권리, 채용, 보안처럼 외부 신뢰가 걸린 업무는 기록이 비용을 줄입니다.

처음부터 완벽한 양식을 만들려고 멈추지 마세요. 한 페이지 표로 시작하고, 월 1회 회고에서 누락된 항목을 보강하면 됩니다. 적용 결과는 처리 시간, 재문의 건수, 이탈률, 환불률, 승인 대기 시간처럼 작은 숫자로 남기면 다음 개선 방향이 보입니다.

예외 처리 기준도 함께 정해야 합니다. 모든 예외를 대표가 판단하면 병목이 생기고, 아무나 판단하면 기준이 흔들립니다. 금액, 고객 영향, 법적 위험, 공개 노출 여부에 따라 어느 단계에서 누가 승인하는지 정하면 빠른 실행과 일관성을 함께 얻을 수 있습니다.

문서의 소유자와 개정 주기도 지정하세요. 담당자가 없는 문서는 오래된 상태로 남고, 오래된 문서는 현장에서 신뢰를 잃습니다. 분기마다 한 번 실제 사례와 비교해 맞지 않는 문장을 고치고, 바뀐 기준은 공지나 회의록에 남겨야 합니다.

고객에게 노출되는 정책이라면 내부 운영표와 외부 안내문을 분리하는 것이 좋습니다. 내부표에는 승인권자, 예외 조건, 증빙 위치를 자세히 쓰고, 외부 안내문에는 고객이 이해해야 할 기준과 문의 경로만 간결하게 담습니다. 두 문서가 같은 기준을 말해야 상담 품질이 흔들리지 않습니다.

또한 정책이 실제로 효과가 있었는지 확인할 지표를 하나만 정해도 좋습니다. 예를 들어 처리 시간, 반복 문의, 반려율, 오류 건수, 재방문율처럼 업무와 직접 연결된 숫자를 보면 됩니다. 지표가 있어야 다음 달에 유지할 기준과 고칠 기준을 구분할 수 있습니다.

실패 사례를 기록하는 습관도 중요합니다. 처리 지연, 잘못된 안내, 권한 회수 누락, 정산 오류처럼 한 번 발생한 문제는 다음 체크리스트의 항목이 됩니다. 작은 실패를 기록으로 바꾸는 팀이 같은 실수를 덜 반복합니다.

자주 묻는 질문

처음에는 어느 정도까지 문서화해야 하나요?

처음부터 긴 규정을 만들기보다 검증, 재시도, 중복처럼 반복해서 판단하는 항목부터 표로 정리하는 것이 좋습니다. 각 항목에 담당자, 판단 기준, 기록 위치, 재검토일을 넣으면 작은 팀에서도 바로 실행할 수 있습니다.

팀원이 문서를 잘 따르지 않으면 어떻게 하나요?

문서가 너무 길거나 실제 도구와 연결되지 않았을 가능성이 큽니다. 결재 문서, 고객센터 매크로, CRM, 대시보드, 계약 폴더처럼 팀원이 매일 쓰는 위치에 체크 항목을 붙이세요. 교육보다 업무 흐름 안에 넣는 편이 오래갑니다.

전문가 검토가 꼭 필요한가요?

고객 권리, 결제, 개인정보, 보안 사고, 계약, 채용처럼 외부 이해관계가 큰 주제라면 전문가 검토를 받는 편이 안전합니다. 다만 전문가에게 맡기기 전에도 회사의 현재 처리 방식과 원하는 기준을 정리해두면 검토 비용과 시간이 줄어듭니다.

작성 후 바로 전면 적용해도 되나요?

최근 사례 3개에 먼저 대입해 보는 편이 좋습니다. 기준이 너무 엄격해서 업무가 멈추는지, 반대로 예외가 많아 정책 의미가 사라지는지 확인한 뒤 팀 공지와 고객 안내 문구를 맞추면 적용 실패가 줄어듭니다.

마무리

웹훅은 자동화의 핵심이지만 실패와 중복을 전제로 설계해야 안정적입니다. 검증, 재시도, 멱등 처리, 운영 알림이 갖춰져야 외부 연동이 고객 경험을 흔들지 않습니다.