업무 API의 멱등 키는 재시도할 때마다 새로 만들어야 할까요?

업무 API의 멱등 키는 같은 작업을 다시 요청할 때 그 작업을 식별하는 값입니다. 새 요청마다 키를 바꾸기보다 제공자의 보관 기간과 입력값 비교 규칙을 확인해야 합니다.

같은 작업과 새 작업의 경계를 먼저 정합니다

회사 시스템이 외부 서비스에 생성 요청을 보낸 뒤 응답을 받지 못한 상황을 가정해 보겠습니다. 담당자가 다시 누른 버튼이 앞선 작업의 결과를 확인하려는 것인지, 별도의 작업을 만들려는 것인지 구분해야 합니다. 탱탱소프트는 연동 기획서에 이 경계를 먼저 적도록 권합니다. 이 글은 보내는 API 요청의 식별자 관리에 관한 안내이며, 받는 웹훅의 서명 검증과는 다른 단계입니다.

Stripe의 멱등 요청 문서는 객체 생성이나 갱신 요청에 멱등 키를 사용해 같은 작업이 두 번 수행되는 것을 피하는 방식을 설명합니다. 여기서 소개하는 세부 동작은 Stripe의 계약이며 모든 업무 API가 같은 방식으로 작동하지는 않습니다.

AI로 생성한 개념 이미지. 실제 사업장 사진이 아닙니다.

키와 함께 어떤 조건을 보관할까요?

Stripe API v1은 엔드포인트 실행이 시작된 요청의 상태 코드와 응답 본문을 저장하며, 같은 키로 다시 요청하면 저장한 응답을 반환한다고 설명합니다. 여기에는 500 오류 응답도 포함됩니다. 입력 검증 실패나 실행 중인 요청과의 충돌처럼 실행이 시작되지 않은 경우에는 같은 방식으로 결과가 저장되지 않습니다. API v2의 재시도 동작은 문서에서 별도로 설명하므로 버전을 확인해야 합니다.

탱탱소프트의 운영 제안은 내부 작업 번호, 외부 서비스와 API 버전, 사용한 키, 요청 조건의 비교값, 확인된 결과를 함께 연결하는 것입니다. 비밀 토큰이나 고객 자료 전체를 로그에 복사할 필요는 없습니다. 같은 키로 금액이나 대상처럼 의미가 달라진 값을 보내도 되는지는 제공자의 계약으로 판단합니다. Stripe API v1은 원래 요청과 매개변수가 다르면 오류를 내는 규칙을 명시합니다.

AI로 생성한 개념 이미지. 실제 사업장 사진이 아닙니다.

오래된 키를 다시 써도 같은 결과가 나오나요?

Stripe API v1 문서는 적어도 24시간이 지난 키를 제거할 수 있으며, 제거된 뒤 그 키를 다시 쓰면 새 요청을 만든다고 설명합니다. 따라서 멱등 키를 회사 업무 기록을 영구히 대신하는 번호로 취급하면 안 됩니다. 같은 문서는 이메일 주소나 개인 식별자 같은 민감한 정보를 키로 쓰지 않도록 안내합니다.

복구 시험에는 같은 키와 같은 입력, 같은 키와 달라진 입력, 보관 기간이 지난 작업을 각각 넣어 볼 수 있습니다. 이는 탱탱소프트의 시험 제안입니다. 실제 결제나 고객 발송이 일어나는 운영 환경 대신 제공자가 허용한 시험 환경에서 확인해야 합니다.

응답과 웹훅은 별도로 대조합니다

Stripe의 웹훅 안내는 이벤트가 생성 순서대로 전달된다고 약속하지 않으며 중복 이벤트 처리도 설명합니다. 보내는 요청에 키를 넣었다는 이유만으로 나중에 받는 알림의 중복·순서 문제가 해결된다고 볼 수 없습니다. 요청 기록과 수신 이벤트 기록을 구분한 뒤 같은 업무 결과에 연결하는 설계가 필요합니다.

청주·충북 기업이 외부 서비스를 연결하려면 서비스명과 API 버전, 중복 수행 시 영향을 먼저 정리해 두는 편이 좋습니다. 탱탱소프트는 이 자료를 바탕으로 온라인 상담에서 자동화 범위와 복구 시험 항목을 정합니다. 이 글은 특정 고객 시스템의 중복 방지 성능을 측정한 결과가 아닙니다.

참고 자료

• Stripe: Idempotent requests
• Stripe: Receive Stripe events in your webhook endpoint