이벤트와 웹훅

정의

이벤트는 입고·출고 등의 업무에 변경이 발생했다는 기록입니다. eventId로 구분하며 발생 시각과 변경 대상, 변경 내용을 담습니다.

웹훅은 이벤트를 고객사가 준비한 수신 URL로 전달하는 방식입니다. 이벤트 조회 API를 이용해 저장된 이벤트를 가져올 수도 있습니다.

최신 상태 조회는 입고·출고 등의 업무 API를 호출해 현재 정보를 읽는 것입니다. 이벤트 본문은 변경이 발생한 시점의 정보이므로 최신 상태와 다를 수 있습니다.

arrival.changed·inbound.changed·outbound.changed는 각각 도착·입고·출고의 변경을 알립니다.
이벤트의 resource는 바뀐 대상을 나타냅니다. 웹훅을 받으면 해당 업무 API로 최신 상태를 조회해 고객사 시스템에 반영합니다.
이벤트 본문에는 일부 목록이 생략될 수 있습니다. 본문을 해당 업무의 전체 최신 상태로 간주하지 않습니다.
도착 기록의 조회 권한이 회수되면 resource.apiPath가 null일 수 있으며, 최신 상세를 조회할 권한도 없어질 수 있습니다.

업무 변경의 이벤트 기록과 웹훅 전송은 별도로 다룹니다. 수신 URL을 등록하기 전의 이벤트가 등록 후 자동으로 모두 전송되는 것은 아닙니다. 처음 연결할 때는 현재 상태와 그 사이의 변경을 함께 동기화합니다.

같은 이벤트가 여러 번 전달되거나 발생 순서와 다르게 도착할 수 있습니다. 재전송 때도 eventId는 유지되지만 전송 시각과 서명은 달라질 수 있습니다.

웹훅의 자동 재시도는 이벤트 발생 후 72시간 또는 실제 자동 시도 256회까지입니다. 이벤트 API의 보관 기간과 커서 유효기간은 30일입니다. 웹훅 재시도 기간과 이벤트 조회·복구 기간을 구분합니다.

수신을 중지했다가 재개하면 재개 이후 이벤트를 전송합니다. 중지 기간의 변경은 이벤트 API로 복구합니다.

커서(cursor)는 다음 이벤트 조회를 이어갈 때 그대로 전달하는 값입니다. 값을 해석하거나 직접 만들지 않습니다.

초기 연결에서는 시작 커서를 저장한 뒤 현재 상태를 동기화하고, 시작 위치 이후 이벤트를 가져옵니다. 이후에도 마지막 저장 커서로 복구를 반복합니다. 각 페이지의 이벤트와 커서는 함께 저장해야 중간 이벤트를 건너뛰지 않습니다.

커서 만료 등으로 410이 발생하면 현재 상태를 재동기화하고 오류가 제공한 복구 커서 이후부터 이벤트를 읽습니다. 보관 기간을 지난 과거 전체 이력이 복원되는 것은 아닙니다.

원래 HTTP 본문 바이트로 서명을 검증합니다. API 인증 정보와 웹훅 서명 키를 구분합니다.
재시작 후에도 유지되는 저장소에 이벤트와 후속 처리 대기 상태를 저장한 뒤 2xx로 응답합니다. 이후 별도 처리에서 최신 상태를 조회합니다.
eventId를 환경·연동 계정과 함께 저장해 중복 처리를 막습니다. 웹훅과 API 복구가 같은 중복 제거 기록을 사용합니다.
sequence는 같은 고객사 안의 이벤트 순서를 나타내는 10진수 문자열입니다. 비교에는 BigInt 등을 사용하고 전송 시각을 중복 제거 기준으로 쓰지 않습니다.
과거 이벤트 본문으로 최신 상태를 덮어쓰지 않습니다. 입고 확인 요청도 최신 내용을 조회·검토한 뒤 처리합니다.
웹훅은 독립적인 상품 변경이나 재고의 모든 변화를 알리지 않습니다. 주기적인 재고 대조도 함께 운영합니다.