웹훅 연동, 중복과 누락에 대비하는 방법

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

오늘의 인사이트 요약

- 수신 응답과 실제 업무 완료를 구분합니다.

- 같은 알림을 다시 받아도 결과가 중복되지 않게 만듭니다.

- 순서가 바뀌거나 알림을 놓쳤을 때의 복구 경로를 둡니다.

여러 서비스를 연결해 운영하다 보면 한쪽에는 완료로 표시되는데 다른 쪽에는 반영되지 않아 당황스러울 때가 있습니다. 연동 테스트에서는 잘됐더라도 일시적인 통신 오류나 재전송이 생기면 평소에는 드러나지 않던 문제가 나타날 수 있는데요.

웹훅은 어떤 일이 발생했을 때 다른 시스템으로 알림을 보내는 방식입니다. 즉, 알림을 받는 주소를 연결하는 것만으로는 중복 처리와 누락까지 해결되지 않습니다.

오늘은 웹훅 연동을 검토할 때 확인할 수신, 중복 방지, 순서 처리, 복구 방법을 정리해보았습니다.

1. 수신과 완료를 구분해야 합니다.

웹훅을 받았다는 응답과 업무가 끝났다는 상태를 나눠 관리해야 합니다.

수신 서버가 성공 응답을 보냈더라도 내부 데이터 갱신이나 후속 알림 발송은 아직 진행 중일 수 있습니다. 운영 화면에서 둘을 모두 ‘성공’으로 표시하면 문제가 어디서 생겼는지 찾기 어려워집니다.

설계할 때는 요청의 출처와 내용을 검증한 뒤 안전하게 저장하고, 시간이 걸리는 처리는 별도 작업으로 넘기는 방법을 검토하세요. 메모리에만 잠깐 올려놓고 성공 응답을 보내면 서버가 중단됐을 때 작업을 잃을 수 있습니다. 저장에 실패한 경우에는 성공으로 응답하지 않고 연동 서비스의 재시도 규칙에 맞춰 처리해야 합니다.

요청의 출처 검증도 함께 확인해야 합니다.

서명을 제공하는 서비스라면 그 서비스가 지정한 방식으로 검증하고, 필요한 경우 원문 요청 본문을 보존해야 합니다. 단순히 주소를 알고 있다는 이유만으로 정상 알림이라고 받아들이면 안 됩니다.

똑똑한개발자팀은 연동 상태를 확인할 때 수신 여부와 업무 반영 여부를 따로 볼 수 있어야 한다고 생각합니다. 이를 구분하면 재전송을 요청할 문제인지, 내부 처리 작업을 다시 돌릴 문제인지 판단하기 쉬워지기 때문입니다.

2. 재전송을 중복 처리하지 않습니다

같은 알림이 다시 왔을 때 이미 처리한 업무인지 확인해야 합니다.

이런 성질을 멱등성이라고 부릅니다. 가령 하나의 완료 알림을 두 번 받았더라도 동일한 이용 권한을 중복 발급하거나 같은 안내를 두 번 보내지 않게 만드는 것입니다.

중복 판단에는 연동 서비스가 제공하는 이벤트 식별자를 활용할 수 있습니다. 다만 서로 다른 이벤트가 같은 업무 결과를 가리킬 수도 있으므로 주문 번호나 처리 종류 등 업무상의 식별 기준도 검토해야 합니다. 반대로 같은 대상에서 발생한 정상적인 후속 변경을 중복으로 버리지 않도록 이벤트의 의미를 확인해야 합니다.

동시에 요청이 들어올 때도 중복을 막을 수 있어야 합니다.

‘처리 기록이 없으면 실행한다’는 조회만으로는 두 작업이 동시에 통과할 수 있습니다. 개발 단계에서 데이터베이스의 유일성 제약이나 트랜잭션처럼 동시에 접근해도 지켜지는 장치를 검토하고, 처리 중·완료·실패 상태를 구분해 두세요.

이미 완료된 작업은 건너뛰되 실패한 작업까지 완료된 것으로 취급하지 않는 것이 중요합니다. 외부 서비스로 다시 요청을 보내는 작업이라면 상대 서비스가 제공하는 중복 방지 기능도 함께 확인해야 합니다.

3. 도착 순서만 믿지 않습니다

늦게 도착한 알림이 더 최신 상태를 뜻하는 것은 아닙니다. 생성된 순서와 전달된 순서가 다를 수 있으므로, 도착한 내용으로 무조건 현재 값을 덮어쓰면 이미 갱신한 상태가 과거로 돌아갈 수 있습니다.

가상의 구독 관리 기능을 생각해 보세요.

구독 변경을 알리는 이벤트가 도착했을 때 저장된 상태만 보고 처리하기 어렵다면, 원본 서비스에서 현재 상태를 다시 조회해 반영하는 방법을 검토할 수 있습니다. 이벤트는 확인을 시작하는 신호로 쓰고, 최종 상태는 원본과 맞추는 방식입니다. 다만 조회에도 실패할 수 있어 재시도와 대기 상태가 필요합니다.

순서 보장 여부, 중복 이벤트, 비동기 처리의 구체적인 예는 Stripe 웹훅 문서에서 더 자세히 보실 수 있습니다. 실제 연동에서는 해당 서비스의 문서를 기준으로 판단해야 하며, 한 서비스의 재전송 기간이나 식별 규칙을 다른 서비스에도 그대로 적용해서는 안 됩니다.

4. 놓친 알림을 다시 확인합니다

자동 재시도가 끝난 뒤에도 반영되지 않은 업무를 찾을 수 있어야 합니다.

실패 항목을 따로 모아 확인하고, 원인을 고친 뒤 선택적으로 다시 처리할 수 있도록 설계하세요. 이때도 중복 방지 규칙을 동일하게 적용해야 복구 과정에서 새로운 중복이 생기지 않습니다.

아예 받지 못한 알림은 수신 로그만으로 찾을 수 없습니다. 원본 서비스의 조회 기능이나 내역을 이용해 내부 기록과 대조하는 방법이 필요합니다. 대조 주기와 조회 범위는 업무가 허용하는 지연, API 제한, 데이터 보관 범위를 함께 고려해 정합니다. 모든 연동을 같은 간격으로 점검할 이유는 없습니다.

우리 시스템에서 변경 사항을 저장하고 알림을 발송하는 경우에는 두 작업 사이의 실패도 살펴야 합니다. 데이터는 바뀌었지만 발송할 내용을 잃어버리는 문제를 줄이려면, 변경 기록과 발송 대상을 함께 저장한 뒤 전달하는 방식을 검토할 수 있습니다.

최종 검수에는 같은 이벤트의 재전송, 순서가 바뀐 전달, 저장 실패, 처리 도중 중단을 포함하는 것이 좋습니다. 정상 요청이 도착하는지만 보는 대신, 실패 이후에도 원래 의도한 결과로 돌아오는지 확인하는 것입니다.

똑똑한개발자는 프로덕트 기획·개발·운영 경험을 바탕으로 기존 시스템과 외부 서비스의 연결을 함께 검토합니다. 데이터가 오가는 경로와 운영 담당자가 확인할 화면을 연결해, 구축 이후의 점검과 개선까지 고려합니다.

서비스 간 데이터 불일치를 줄이거나 연동 이후의 복구 방법을 정하고 싶다면 아래 똑똑한개발자 링크로 이야기 나눠주세요! 감사합니다. :)