웹후크 신뢰성 체크리스트: 재시도, 멱등성, 재실행

실제 프로젝트에서 웹후크가 신뢰할 수 없게 느껴지는 이유

웹후크는 간단한 개념입니다. 어떤 일이 발생하면 한 시스템이 다른 시스템으로 HTTP 요청을 보냅니다. "주문 발송됨", "티켓 업데이트됨", "장치 오프라인" 같은 알림입니다. 앱 사이의 푸시 알림을 웹을 통해 전달하는 셈이죠.

데모에서는 정상 경로가 빨라서 신뢰할 수 있어 보입니다. 실제 현업에서는 웹후크가 당신이 통제하지 못하는 시스템들 사이에 놓입니다: CRM, 배송업체, 헬프데스크, 마케팅 도구, IoT 플랫폼, 심지어 다른 팀이 소유한 내부 앱까지. 결제 분야를 제외하면 성숙한 전달 보증, 안정적인 이벤트 스키마, 일관된 재시도 동작을 기대하기 어렵습니다.

문제의 첫 징후는 보통 혼란스럽습니다:

• 중복 이벤트(같은 업데이트가 두 번 도착함)
• 누락된 이벤트(무언가 변경됐는데 알림을 못 받음)
• 지연(업데이트가 몇 분 또는 몇 시간 뒤에 도착)
• 순서 뒤바뀜(예: "closed"가 "opened"보다 먼저 도착)

불안정한 서드파티 시스템은 실패가 항상 크게 드러나지 않기 때문에 무작위처럼 느껴집니다. 제공자가 타임아웃을 내지만 실제로는 요청을 처리했을 수도 있고, 로드밸런서가 송신자가 이미 재시도한 뒤 연결을 끊을 수도 있습니다. 또는 시스템이 잠깐 다운됐다가 오래된 이벤트들을 한꺼번에 밀어낼 수도 있습니다.

예를 들어 배송 파트너가 "delivered" 웹후크를 보낸다고 합시다. 어느 날 수신 측이 3초 동안 느려서 파트너가 재시도합니다. 당신은 두 번의 "배달됨"을 받고 고객에게 이메일이 두 번 가고 지원팀은 혼란스러워합니다. 다음 날 파트너가 장애를 겪어 재시도도 하지 않으면 "delivered"가 전혀 도착하지 않아 대시보드가 갱신되지 않을 수 있습니다.

웹후크 신뢰성은 하나의 완벽한 요청이 중요하다기보다 혼란스러운 현실을 감당하도록 설계하는 것입니다: 재시도, 멱등성, 나중에 재실행하고 확인할 수 있는 능력입니다.

세 가지 기반: 재시도, 멱등성, 재실행

웹후크는 인바운드(당신이 받는 호출)와 아웃바운드(당신이 보내는 호출) 두 방향으로 옵니다. 둘 다 당신의 코드와 무관한 이유로 실패할 수 있습니다.

재시도는 실패 후 일어나는 행동입니다. 발신자는 타임아웃, 500 에러, 연결 끊김 또는 응답 지연 때문에 재시도할 수 있습니다. 좋은 재시도는 드문 예외가 아니라 예상되는 동작입니다. 목표는 수신자를 폭주시키거나 부작용을 중복 생성하지 않으면서 이벤트를 전달하는 것입니다.

멱등성은 중복을 안전하게 만드는 방법입니다. "한 번만 실행되게 하기(여러 번 도착해도)"를 의미합니다. 같은 웹후크가 다시 도착하면 이를 감지하고 비즈니스 동작을 두 번째로 실행하지 않고 성공 응답을 반환합니다(예: 두 번째 청구서 생성하지 않기).

재실행은 복구 버튼입니다. 버그를 고친 후나 파트너가 다운된 뒤 제어된 방식으로 과거 이벤트를 재처리할 수 있는 능력입니다. 재시도는 자동이고 즉각적이지만 재실행은 의도적이며 몇 시간이나 며칠 후에 일어날 수 있습니다.

웹후크 신뢰성을 원한다면 몇 가지 목표를 세우고 그에 맞춰 설계하세요:

• 이벤트가 절대 사라지지 않음(무엇이 도착했는지, 무엇을 보내려 했는지 항상 찾을 수 있음)
• 중복이 안전함(재시도와 재실행이 중복 요금 청구, 중복 생성, 중복 이메일을 발생시키지 않음)
• 명확한 감사 기록(무슨 일이 있었는지 빠르게 답할 수 있음)

실용적인 방법은 모든 웹후크 시도를 상태와 고유 멱등성 키와 함께 저장하는 것입니다. 많은 팀이 이를 작은 "webhook inbox/outbox" 테이블로 구현합니다.

인바운드 웹후크: 재사용 가능한 수신 흐름

대부분의 웹후크 문제는 발신자와 수신자가 다른 시계(clock)를 쓰는 데서 발생합니다. 수신자의 역할은 예측 가능해지는 것입니다: 빠르게 수신을 인정하고, 도착한 내용을 기록하며, 안전하게 처리하세요.

"수락"과 "실제 작업" 분리하기

HTTP 요청을 빠르게 처리하고 실제 작업은 다른 곳으로 옮기는 흐름으로 시작하세요. 이렇게 하면 타임아웃이 줄고 재시도가 훨씬 덜 고통스러워집니다.

• 빠르게 인정하세요. 요청이 수락 가능하면 가능한 빨리 2xx를 반환합니다.
• 기본 사항을 확인하세요. Content-Type, 필수 필드, 파싱을 검증합니다. 웹후크에 서명이 있으면 여기에서 검증하세요.
• 원시 이벤트를 영속화하세요. 본문과 나중에 필요할 헤더(서명, 이벤트 ID), 수신 타임스탬프와 "received" 같은 상태를 저장합니다.
• 작업을 큐에 넣으세요. 백그라운드 처리를 위한 작업을 생성한 뒤 2xx를 반환합니다.
• 명확한 결과로 처리하세요. 사이드 이펙트가 성공했을 때만 이벤트를 "processed"로 표시합니다. 실패하면 이유와 재시도 여부를 기록하세요.

"빠르게 응답"은 어떤 모습인가

현실적인 목표는 1초 이내에 응답하는 것입니다. 발신자가 특정 코드를 기대하면 그것을 사용하세요(많은 경우 200을 수용하고, 어떤 경우에는 202를 선호). 발신자가 재시도하면 안 되는 경우(예: 잘못된 서명)만 4xx를 반환하세요.

예: 데이터베이스가 과부하인 동안 "customer.created" 웹후크가 도착해도 이 흐름이면 원시 이벤트를 저장하고, 큐에 넣고 2xx로 응답할 수 있습니다. 워커는 발신자가 재전송하지 않아도 나중에 재시도할 수 있습니다.

전달을 깨뜨리지 않는 인바운드 안전 체크

보안 검사는 가치가 있지만 목표는 나쁜 트래픽을 막되 정상 이벤트를 막지 않는 것입니다. 많은 전달 문제는 수신자가 너무 엄격하거나 잘못된 응답을 반환해서 발생합니다.

먼저 발신자를 증명하세요. 서명(HMAC 서명 헤더)이나 헤더의 공유 비밀 토큰을 선호합니다. 큰 작업을 하기 전에 이를 검증하고, 누락되었거나 잘못되면 빠르게 실패 처리하세요.

상태 코드는 재시도를 제어하므로 주의해서 사용하세요:

• 인증 실패에는 401/403을 반환해 발신자가 무한히 재시도하지 않게 합니다.
• 잘못된 JSON이나 필수 필드 누락에는 400을 반환합니다.
• 귀하의 서비스가 일시적으로 처리할 수 없을 때만 5xx를 사용하세요.

IP 허용 목록은 제공자가 안정적이고 문서화된 IP 범위를 제공할 때만 도움이 됩니다. IP가 자주 바뀌거나 큰 클라우드 풀을 쓰면 허용 목록이 실제 웹후크를 조용히 차단할 수 있고 문제를 훨씬 뒤에야 발견할 수 있습니다.

공급자가 타임스탬프와 고유 이벤트 ID를 포함하면 재생 보호를 추가할 수 있습니다: 너무 오래된 메시지는 거부하고 최근 ID를 추적해 중복을 감지하세요. 시간 창은 작게 유지하되 시계 차이(clock drift)가 정상적인 요청을 깨지 않도록 여유를 둡니다.

수신자 친화적인 보안 체크리스트:

• 큰 페이로드를 파싱하기 전에 서명 또는 공유 비밀을 검증하세요.
• 최대 본문 크기를 강제하고 짧은 요청 타임아웃을 사용하세요.
• 인증 실패나 잘못된 스키마에는 401/403 또는 400을 사용하고, 수락된 이벤트에는 2xx를 반환하세요.
• 타임스탬프를 검증하면 몇 분 정도의 여유를 허용하세요.

로깅을 위해 민감한 데이터를 영원히 보관하지 않고도 감사 로그를 유지하세요. 이벤트 ID, 발신자 이름, 수신 시간, 검증 결과, 원시 본문 해시를 저장하세요. 페이로드를 저장해야 한다면 보존 기간을 설정하고 이메일, 토큰, 결제 정보는 마스킹하세요.

도움이 되는 재시도 설계

재시도는 일시적인 문제를 성공 전달로 바꿀 때 유용합니다. 트래픽을 증폭하고 실제 버그를 숨기거나 중복을 만들 때 해로워집니다. 차이는 무엇을 재시도할지, 어떻게 간격을 둘지, 언제 멈출지에 대한 명확한 규칙이 있는지에 달려 있습니다.

기본 원칙은 수신자가 나중에 성공할 가능성이 있을 때만 재시도하는 것입니다. 직관적으로는 "일시적 실패에는 재시도, 당신이 잘못 보낸 것에는 재시도 금지"입니다.

실무적인 HTTP 결과 분류:

• 재시도 대상: 네트워크 타임아웃, 연결 오류, HTTP 408, 429, 500, 502, 503, 504
• 재시도 금지: HTTP 400, 401, 403, 404, 422
• 상황에 따라: HTTP 409(때로는 중복, 때로는 실제 충돌)

간격 설정이 중요합니다. 많은 이벤트가 동시에 실패할 때 재시도 폭풍을 만들지 않도록 지터가 있는 지수적 백오프를 사용하세요. 예: 5초, 15초, 45초, 2분, 5분 등으로 늘리고 각 시도에 작은 무작위 오프셋을 추가합니다.

또한 최대 재시도 기간과 명확한 마감선을 정하세요. 일반적인 선택지는 "최대 24시간 동안 재시도"하거나 "10회 이하 재시도" 같은 규칙입니다. 그 이후에는 전달 문제가 아니라 복구 문제로 간주하세요.

일상에서 작동하게 하려면 이벤트 기록에 다음을 캡처하세요:

• 시도 횟수
• 마지막 오류
• 다음 재시도 시각
• 최종 상태(재시도를 중단했을 때의 dead-letter 상태 포함)

Dead-letter 항목은 검사하기 쉽고 근본 원인을 고친 후 안전하게 재실행할 수 있어야 합니다.

실무에서 통하는 멱등성 패턴

멱등성은 같은 웹후크를 여러 번 처리해도 부작용을 추가로 만들지 않게 하는 것입니다. 재시도와 타임아웃은 누구도 안 하는데도 발생하므로 멱등성은 신뢰성을 빠르게 개선합니다.

안정적인 키 선택하기

공급자가 이벤트 ID를 준다면 그걸 사용하세요. 가장 깔끔한 옵션입니다.

이벤트 ID가 없다면 안정적인 필드에서 키를 만드세요. 예를 들어 다음과 같은 해시를 사용합니다:

• 공급자 이름 + 이벤트 타입 + 리소스 ID + 타임스탬프
• 공급자 이름 + 메시지 ID

키와 함께 소량의 메타데이터(수신 시간, 공급자, 이벤트 타입, 처리 결과)를 저장하세요.

일반적으로 지켜야 할 규칙:

• 키를 필수로 다루세요. 키를 만들 수 없으면 추측하지 말고 이벤트를 격리하세요.
• 테이블이 무한히 커지지 않도록 TTL(예: 7~30일)을 설정하세요.
• 처리 결과도 저장해(성공, 실패, 무시) 중복이 일관된 응답을 받게 하세요.
• 두 병렬 요청이 둘 다 실행되지 않도록 키에 유니크 제약을 걸어두세요.

비즈니스 동작 자체도 멱등하게 만들기

좋은 키 테이블이 있어도 실제 작업이 안전해야 합니다. 예: "주문 생성(create order)" 웹후크는 데이터베이스 삽입 시 첫 시도가 타임아웃 난 후 두 번째 시도가 도착해 두 번째 주문을 만들면 안 됩니다. external_order_id 같은 자연식별자를 사용해 upsert 패턴을 쓰세요.

순서가 뒤바뀔 수 있으니 대비하세요. "user_updated"가 "user_created"보다 먼저 도착하면 event_version이 더 최신일 때만 적용하거나 updated_at이 더 최신일 때만 업데이트하는 규칙을 적용할 수 있습니다.

서로 다른 페이로드를 가진 중복은 가장 까다롭습니다. 미리 정책을 정하세요:

• 키는 같은데 페이로드가 다르면 공급자 버그로 보고 경고를 울리세요.
• 키는 같은데 차이가 사소한 필드라면 무시하세요.
• 공급자를 신뢰할 수 없다면 전체 페이로드 해시에 기반한 파생 키로 전환하고 충돌을 새로운 이벤트로 처리하세요.

목표는 단순합니다: 현실 세계의 한 변화가 메시지를 세 번 보든 한 번의 실제 결과만 만들어야 합니다.

복구를 위한 재실행 도구와 감사 로그

파트너 시스템이 불안정하면 신뢰성은 전달의 완벽성보다 빠른 복구에 달려 있습니다. 재실행 도구는 "이벤트를 잃었다"는 상황을 위기 대신 일상 업무로 바꿉니다.

먼저 각 웹후크의 라이프사이클(수신, 처리됨, 실패, 무시)을 추적하는 이벤트 로그를 만드세요. 시간, 이벤트 타입, 상관 ID로 검색할 수 있게 하면 지원팀이 "주문 18432에 무슨 일이 있었나요?"에 빠르게 답할 수 있습니다.

각 이벤트에 대해 나중에 동일한 결정을 다시 내릴 수 있을 만큼의 컨텍스트를 저장하세요:

• 원시 페이로드와 주요 헤더(서명, 이벤트 ID, 타임스탬프)
• 추출한 정규화된 필드
• 처리 결과와 오류 메시지(있다면)
• 당시 사용된 워크플로 또는 매핑 버전
• 수신, 시작, 종료 타임스탬프

이것이 준비되면 실패한 이벤트에 대한 "재실행(Replay)" 액션을 추가하세요. 버튼 자체보다 가드레일이 더 중요합니다. 좋은 재실행 흐름은 이전 오류, 재실행 시 일어날 일, 이벤트를 다시 실행해도 안전한지 여부를 보여줘야 합니다.

우발적 피해를 막는 가드레일:

• 재실행 사유를 요구하세요.
• 재실행 권한을 소수의 역할로 제한하세요.
• 처음 처리와 동일한 멱등성 검사를 재실행에도 적용하세요.
• 인시던트 중 재실행으로 새로운 스파이크가 생기지 않도록 속도 제한(rate-limit)을 적용하세요.
• 선택적 드라이런 모드로 쓰기 없이 검증만 할 수 있게 하세요.

인시던트는 종종 여러 이벤트가 얽혀 있으니 시간 범위로 재실행할 수 있게 지원하세요(예: "10:05부터 10:40 사이의 실패한 모든 이벤트 재실행"). 누가 언제 왜 재실행했는지도 기록하세요.

아웃바운드 웹후크: 감사 가능한 발신 흐름

아웃바운드 웹후크 실패는 대부분 지루한 이유 때문입니다: 수신자의 느린 응답, 잠깐의 장애, DNS 문제, 또는 프록시가 긴 요청을 자르는 등. 신뢰성은 모든 전송을 추적 가능하고 재현 가능한 작업(job)으로 다루는 것에서 옵니다.

예측 가능한 발신 흐름

모든 이벤트에 안정적인 고유 이벤트 ID를 부여하세요. 이 ID는 재시도, 재실행, 서비스 재시작에도 동일하게 유지되어야 합니다. 시도마다 새 ID를 만들면 수신자의 중복 제거와 귀하의 감사가 어려워집니다.

각 요청에 서명하고 타임스탬프를 포함하세요. 타임스탬프는 수신자가 매우 오래된 요청을 거부하는 데 도움이 되고, 서명은 페이로드가 전송 중 변경되지 않았음을 증명합니다. 서명 규칙은 단순하고 일관되게 유지해 파트너가 구현하기 쉬워야 합니다.

배송 기록은 이벤트별이 아니라 엔드포인트별로 추적하세요. 동일한 이벤트를 세 곳에 보내면 각 목적지는 고유한 시도 이력과 최종 상태가 필요합니다.

대부분의 팀이 구현할 수 있는 실용적 흐름:

• 이벤트 레코드를 생성(이벤트 ID, 엔드포인트 ID, 페이로드 해시, 초기 상태 포함)
• 서명, 타임스탬프, 멱등성 키 헤더와 함께 HTTP 요청 전송
• 모든 시도(시작 시간, 종료 시간, HTTP 상태, 짧은 오류 메시지)를 기록
• 타임아웃과 5xx에 대해서만 지수적 백오프와 지터로 재시도
• 명확한 한계(최대 시도 횟수 또는 최대 연령)에 도달하면 실패로 표시하고 검토로 옮김

이 멱등성 키 헤더는 발신자일 때도 중요합니다. 수신자가 첫 번째 요청을 처리했지만 귀하의 클라이언트가 200 응답을 받지 못했을 때 중복 제거 수단을 제공합니다.

마지막으로 실패를 가시화하세요. "실패"가 곧 "손실"을 의미하면 안 됩니다. "중단되었지만 안전하게 재실행할 수 있는 충분한 컨텍스트가 있는 상태"여야 합니다.

예: 불안정한 파트너 시스템과 깔끔한 복구

지원 앱에서 파트너 시스템으로 티켓 업데이트를 보내 파트너 에이전트가 동일한 상태를 보게 합니다. 티켓이 변경(할당됨, 우선순위 변경, 종료)될 때마다 ticket.updated 같은 웹후크 이벤트를 전송합니다.

어느 날 파트너의 엔드포인트가 타임아웃을 여러 번 내기 시작합니다. 첫 번째 전송 시도가 타임아웃에 걸리고 귀하는 그 결과를 알 수 없어 "미확인"으로 처리합니다(도착했을 수도 있고 아닐 수도 있음). 좋은 재시도 전략은 초당 수차례 반복 전송하는 대신 백오프로 재시도합니다. 이벤트는 동일한 이벤트 ID로 큐에 남고 각 시도는 기록됩니다.

이제 골치 아픈 부분: 멱등성을 사용하지 않으면 파트너가 중복 처리할 수 있습니다. 1번째 시도가 파트너에 도달했지만 응답이 돌아오지 않았을 수 있고 2번째 시도가 도착해 두 번째 "Ticket closed" 동작을 만들어 이메일이 두 통 가거나 타임라인 항목이 두 개 만들어질 수 있습니다.

멱등성을 적용하면 각 전송에 이벤트에서 유도한 멱등성 키(보통 이벤트 ID)를 포함합니다. 파트너는 일정 기간 해당 키를 저장하고 반복된 요청에 대해 "이미 처리됨"을 응답합니다. 귀하는 더 이상 추측하지 않아도 됩니다.

파트너가 복구되면 재실행으로 누락된 업데이트(예: 장애 기간 중 우선순도 변경)를 복구합니다. 감사 로그에서 이벤트를 골라 동일한 페이로드와 멱등성 키로 한 번 재실행하면 이미 받았어도 안전합니다.

인시던트 동안 로그는 상황을 명확히 보여줘야 합니다:

• 이벤트 ID, 티켓 ID, 이벤트 타입, 페이로드 버전
• 시도 번호, 타임스탬프, 다음 재시도 시간
• 타임아웃인지 비2xx 응답인지 성공인지
• 전송된 멱등성 키와 파트너가 "중복"을 보고했는지 여부
• 누가 재실행했는지와 최종 결과를 보여주는 재실행 기록

흔한 실수와 함정

대부분의 웹후크 인시던트는 한 번의 큰 버그 때문이 아닙니다. 트래픽 급증이나 서드파티 불안정이 닥쳤을 때 신뢰성을 조용히 깨는 작은 선택들이 쌓여서 발생합니다.

사후 분석에서 자주 드러나는 함정:

• 요청 핸들러 안에서 느린 작업(데이터베이스 쓰기, API 호출, 파일 업로드)을 처리해 발신자가 타임아웃하고 재시도하게 함
• 공급자가 중복을 보내지 않을 것이라고 가정하고 중복 청구, 중복 주문 생성, 중복 이메일 발송을 함
• 잘못된 상태 코드 반환(수락하지 않았는데 200 반환, 또는 재시도로 해결될 수 없는 잘못된 데이터에 500 반환)
• 상관 ID, 이벤트 ID, 요청 ID 없이 배포해 로그와 고객 리포트를 매칭하는 데 수시간 소모
• 무한히 재시도해 백로그를 만들고 파트너 장애를 자체 장애로 확산시킴

간단한 규칙이 통합니다: 빠르게 인정하고, 안전하게 처리하세요. 수락 여부를 결정하는 데 필요한 것만 검증하고 저장한 뒤 나머지는 비동기로 처리하세요.

상태 코드는 생각보다 중요합니다:

• 2xx는 이벤트를 저장(또는 큐에 넣음)했고 처리될 것이라는 확신이 있을 때만 사용하세요.
• 4xx는 발신자가 재시도해도 해결될 수 없는 잘못된 입력이나 인증 실패에 사용하세요.
• 5xx는 귀하 쪽의 일시적 문제에만 사용하세요.

재시도 상한을 정하세요. 고정 창(예: 24시간)이나 고정 시도 횟수에 도달하면 "검토 필요"로 표시해 사람이 재실행 여부를 결정하게 하세요.

빠른 체크리스트와 다음 단계

웹후크 신뢰성은 대부분 반복 가능한 습관에 관한 것입니다: 빠르게 수락하고, 적극적으로 중복 제거하며, 신중하게 재시도하고, 재실행 경로를 유지하세요.

인바운드(수신자) 빠른 점검 항목

• 요청이 안전하게 저장되면(느린 작업은 비동기로) 빠른 2xx를 반환하세요.
• 디버깅을 위해 수신한 내용을 충분히 저장하세요.
• 멱등성 키를 요구하거나(또는 공급자+이벤트 ID에서 유도) 데이터베이스에서 강제하세요.
• 잘못된 서명이나 스키마에는 4xx를, 실제 서버 문제에는 5xx를 사용하세요.
• 처리 상태(수신됨, 처리됨, 실패)와 마지막 오류 메시지를 추적하세요.

아웃바운드(발신자) 빠른 점검 항목

• 이벤트별로 고유 이벤트 ID를 부여하고 시도 사이에 안정적으로 유지하세요.
• 모든 요청에 서명하고 타임스탬프를 포함하세요.
• 재시도 정책(백오프, 최대 시도, 중단 기준)을 정의하고 준수하세요.
• 엔드포인트별 상태를 추적하세요: 마지막 성공, 마지막 실패, 연속 실패 수, 다음 재시도 시간.
• 모든 시도를 감사와 지원에 충분한 상세로 로깅하세요.

운영 측면에서는 무엇을 재실행할지(단일 이벤트, 시간 범위/상태별 배치, 또는 둘 다), 누가 재실행할 수 있는지, dead-letter 검토 루틴을 미리 결정하세요.

직접 모든 걸 연결하지 않고 이 요소들을 구축하고 싶다면, AppMaster 같은 노코드 플랫폼은 실용적인 선택이 될 수 있습니다. AppMaster에서 PostgreSQL에 webhook inbox/outbox 테이블을 모델링하고, 비즈니스 프로세스 에디터로 재시도와 재실행 흐름을 시각적으로 구현하며, 파트너가 불안정할 때 실패한 이벤트를 검색하고 재실행할 수 있는 내부 관리자 패널을 빠르게 배포할 수 있습니다.