초기 동기화와 누락 복구

웹훅을 받는 동안에도 현재 상태와 이벤트를 어디까지 저장했는지 함께 관리해야 합니다. 수신기가 재시작돼도 이벤트가 유지되도록 저장하고 중복을 제거하는 처리를 먼저 준비하세요. 커서의 역할은 핵심 개념을 참고하고, 아래에서 현재 상황에 맞는 절차를 따르세요.

처음 연결할 때

목표: 현재 상태를 가져오는 동안 생긴 변경을 놓치지 않고 실시간 처리로 이어갑니다.

현재 상태를 가져오는 동안의 변경도 이어서 반영

이 작업이 진행되는 동안

새 웹훅은 계속 저장

서명을 검증하고 이벤트·처리 대기 상태를 저장한 뒤 수신에 응답합니다.

후속 처리는 동기화 완료까지 대기

웹훅과 이벤트 API는 같은 저장소에서 eventId로 중복을 제거합니다. 이벤트와 커서는 페이지마다 함께 저장합니다.

1. GET /api/v1/events/checkpoint에서 시작 위치 C0를 받아 저장합니다.
2. 입고·출고·재고 조회 API로 현재 상태를 가져와 고객사 시스템에 저장합니다. 이 작업 중 받은 이벤트는 저장하되 후속 처리는 대기합니다.
3. GET /api/v1/events?after=C0&limit=50으로 시작 위치 이후 이벤트를 가져와 같은 수신 저장소에 중복 제거해 저장합니다.
4. 각 페이지의 이벤트 저장과 커서 갱신을 같은 데이터베이스 트랜잭션으로 저장합니다. 두 값이 함께 저장되거나 함께 실패해야 이벤트를 건너뛰지 않습니다. nextCursor를 다음 after로 사용해 hasMore=false까지 반복합니다.
5. 초기 동기화 완료를 기록한 뒤 대기 이벤트를 처리하고, 웹훅 연결 뒤에도 저장한 커서로 복구를 수행합니다.

정상 운영과 중단 후 복구

목표: 웹훅 수신 여부와 별개로 마지막으로 저장한 커서 이후 이벤트를 확인합니다. 수신 중지 후 재개하면 재개 시점 이후 이벤트만 전송되므로, 중지 기간은 API로 복구해야 합니다.

마지막으로 저장한 커서를 after로 사용해 이벤트를 읽고, 초기 연결의 3~4단계와 같은 저장·중복 제거 절차를 반복합니다. 웹훅과 API 복구는 같은 이벤트 저장소를 사용합니다. 최신 업무 상태는 API로 조회하고, Maybox와 고객사 시스템의 재고를 주기적으로 비교하는 작업도 계속합니다.

페이지 처리를 끝내는 조건

이벤트가 없는 페이지도 커서를 갱신하고 hasMore를 확인합니다. windowCursor는 이번 조회 범위의 끝을 나타냅니다. 앞선 페이지의 이벤트를 모두 저장하기 전에 이 값을 마지막 저장 위치로 기록하면 중간 이벤트를 건너뛸 수 있습니다. 페이지 처리 후 저장한 커서로 주기적인 복구를 계속합니다.

커서가 만료됐을 때

이벤트 보관과 커서 유효기간은 30일입니다. 커서 만료 또는 보관 범위 밖으로 410이 발생하면 같은 요청을 반복하지 않고 다음 순서로 재개합니다.

1. 오류의 data.recoveryCursor를 저장합니다.
2. 필요한 업무의 현재 상태를 재동기화합니다.
3. 저장한 복구 커서 이후 이벤트를 읽고 정상 복구 절차로 돌아갑니다.

과거 전체 이력이 복원되지는 않으므로 업무에 필요한 수신 기록은 고객사에서 보관합니다.

복구가 가능한지 확인

초기 동기화 중 변경, 중복 수신, 수신 중지·재개와 처리 프로그램 재시작을 시험합니다. 이벤트와 커서가 함께 저장되고 처리 대기 중인 이벤트를 다시 처리할 수 있는지 확인합니다. 운영 중에는 마지막으로 저장한 커서와 마지막 수신·처리 성공 시각을 남겨 중단 위치를 판단합니다.

API의 쿼리 파라미터와 응답 필드는 API 레퍼런스의 이벤트 항목에서 확인하세요.