수신과 업무 완료를 분리하세요
이벤트 전달은 정확히 한 번 실행을 보장하지 않습니다
웹훅은 반복 조회를 알림으로 바꾸지만 네트워크의 불확실성을 없애지는 않습니다. Stripe는 재시도, 중복 전달 가능성과 이벤트 순서를 보장하지 않는다는 점을 문서화합니다. 시연에서 본 깔끔한 순서가 아니라 그 계약을 기준으로 설계하세요.[1]
가상의 실패 상황을 생각해 보세요. 작업자가 주문 이행 요청을 보낸 직후 완료 기록을 남기기 전에 종료됩니다. 다시 처리하면 요청이 중복될 수 있고 모든 재시도를 거부하면 미완료 작업을 잃을 수 있습니다. 목표는 핸들러가 한 번만 실행된다는 약속이 아니라 통제되고 반복해도 안전한 업무 결과입니다.[1]
신뢰할 수 있는 작업으로 넣기 전에 검증하세요
Stripe에서는 공식 라이브러리에 원본 본문, 서명 헤더와 엔드포인트 서명 비밀키를 전달해 검증합니다. 검증 전에 JSON 파서가 원본 바이트를 바꾸면 검사가 실패할 수 있습니다. 직접 만든 객체를 넣은 보조 함수만 시험하지 말고 프레임워크의 실제 요청 경로를 확인하세요.[1]
인증 뒤에도 이벤트 종류, 기대한 계정 맥락과 처리에 필요한 필드를 검증합니다. 테스트와 운영 설정을 분리하세요. 요청자가 전달한 고객·테넌트 식별자만으로 다른 계정을 수정할 권한을 부여하면 안 됩니다. 로그에는 비밀키나 불필요한 고객 본문 대신 이벤트 식별자와 제한된 오류 코드를 남기는 편이 안전합니다.[1]
메모리 속 약속이 아니라 영속적 접수에 응답하세요
Stripe는 신속한 성공 응답과 복잡한 작업의 비동기 처리를 권장합니다. 이 글의 구현 권고는 응답 전에 검증된 이벤트를 영속 저장소에 커밋하는 것입니다. 저장이 실패하면 실패 응답으로 발신자의 재시도를 유도합니다. 메모리에만 있는 백그라운드 작업은 성공 응답 뒤 프로세스가 종료되면 사라질 수 있습니다.[1]
작은 데이터베이스 수신함으로도 시작할 수 있습니다. 존재 여부 조회 뒤 삽입하는 두 단계 대신 제공자, 관련 계정 맥락과 이벤트 ID의 고유 키를 데이터베이스에서 강제하세요. 수신, 처리 중, 완료와 실패 상태를 구분합니다. 작업 점유는 원자적으로 하고 점유한 작업자가 종료됐을 때 제한된 절차로 회수할 수 있게 만듭니다.[1]
이벤트 중복 제거와 업무 멱등성은 다릅니다
이벤트 ID는 같은 이벤트의 반복 전달을 잡습니다. 서로 다른 이벤트가 같은 주문 이행을 요청하는 것까지 자동으로 막지는 않습니다. Stripe도 별도 Event 객체가 중복되는 경우를 설명하며 객체 ID와 이벤트 종류로 식별하도록 안내합니다. 최종 보호 장치는 결제된 주문을 한 번만 이행하는 것처럼 업무 의미에 맞춰 선택하세요.[1][2]
로컬 데이터베이스 변경이라면 보호된 상태 전이와 완료 표시를 한 트랜잭션에 커밋합니다. 외부 작업은 해당 서비스의 멱등성 기능이 있다면 안정적인 작업 키와 함께 사용하세요. Stripe API의 멱등성 키는 문서화된 계약 안에서 외부로 보내는 요청을 보호할 뿐, 들어오는 웹훅 핸들러를 중복 제거하지 않습니다. 개인정보를 키로 쓰거나 제공자가 키를 영구 보관한다고 가정하지 마세요.[1][2]
늦게 온 이벤트가 현재 상태라는 뜻은 아닙니다
오래된 스냅샷이 나중에 도착했다는 이유로 현재 구독이나 주문 상태를 덮어쓰지 마세요. Stripe는 순서를 보장하지 않으며 초 단위 created 필드를 순서·중복 판정에 쓰지 말라고 안내합니다. 허용된 상태 전이를 모델링하고 현재 상태가 필요하면 권위 있는 리소스를 조회하세요.[1]
대사 작업도 필요합니다. 중요한 로컬 결과를 제공자 기록과 주기적으로 비교하고 누락 작업을 찾으며 모호한 경우는 검토 대상으로 보냅니다. 이벤트, 리소스, 시도한 처리와 최종 결과를 연결하는 감사 이력을 유지하세요. 수동 재처리도 관리용 지름길로 통제를 우회하지 말고 일반 전달과 같은 보호 경로를 이용해야 합니다.[1]
각 단계 사이의 실패를 시험하세요
잘못된 서명, 동시 중복 전달, 데이터베이스 장애, 외부 동작 직후 작업자 종료, 늦은 이벤트와 수동 재처리를 시험하세요. HTTP 상태만 보지 말고 최종 업무 레코드와 외부 동작 횟수를 확인합니다. 재시도 시험을 위해 실제 결제를 만들지 말고 sandbox와 시험 데이터를 사용하세요.[1]
가장 오래된 미완료 이벤트의 나이, 재시도 소진과 대사 차이를 모니터링합니다. 재시도 한도와 지속 실패 검토 대기열을 두세요. 엔드포인트가 정상이어도 밀린 작업이 늘면 수신은 성공하고 처리는 실패하는 상태이므로 각각 경보를 설정해야 합니다.[1]
- 잘못된 요청은 신뢰된 처리 경로에 들어가지 않습니다.
- 접수한 이벤트는 프로세스 재시작 후에도 남습니다.
- 동시 중복은 보호된 업무 결과 하나로 끝납니다.
- 실패 작업은 보이고 안전하게 재처리할 수 있습니다.