카페24 주문 상태를 웹훅으로 실시간 연동한 사례

카페24에서 주문 상태가 변경되면 ERP, 물류 시스템, 자체 관리 화면에도 빠르게 반영해야 하는 경우가 있습니다.

이번 사례에서는 카페24 주문 상태 변경을 웹훅으로 받아 외부 시스템과 운영 화면에 거의 실시간으로 반영하는 방식을 적용했습니다.

웹훅 수신 서버를 별도로 구성하고, 중복 처리 방지와 실패 시 재시도까지 함께 설계했습니다.

카페24 관리자에서는 주문 상태가 바로 변경됩니다.

하지만 ERP나 물류 시스템, 자체 운영 화면은 카페24와 별도로 동작합니다.

그래서 다음과 같은 방식으로 데이터를 맞추는 쇼핑몰이 많습니다.

이 방식은 주문량이 적을 때는 큰 문제가 없을 수 있습니다.

하지만 주문량이 많아지거나 배송과 취소가 자주 발생하면 문제가 생깁니다.

예를 들어 고객의 주문이 카페24에서는 이미 배송중으로 변경됐는데 ERP에는 아직 입금완료로 표시될 수 있습니다.

그러면 고객 문의와 실제 내부 데이터가 달라집니다.

출고 담당자가 잘못된 상태를 확인하거나 CS 담당자가 다시 카페24 관리자에서 주문 상태를 확인해야 하는 상황도 발생합니다.

일반적인 카페24 쇼핑몰만으로는 외부 ERP나 자체 DB에 주문 상태를 실시간으로 자동 전달하는 구조를 바로 만들기 어렵습니다.

일부 앱이나 연동 기능을 사용할 수 있는 경우도 있지만, 쇼핑몰마다 필요한 데이터와 업무 규칙이 다릅니다.

특히 다음과 같은 요구사항이 있다면 별도의 연동 개발이 필요할 수 있습니다.

이번 사례에서도 단순히 주문 목록을 반복 조회하는 것보다 주문 상태가 변경되는 순간을 서버에서 받아 처리하는 방식이 적합했습니다.

핵심은 카페24 웹훅 → 별도 서버 → 외부 시스템 구조입니다.

카페24에서 주문과 관련된 이벤트가 발생하면 웹훅을 통해 지정된 서버 주소로 알려줍니다.

전체적인 흐름은 다음과 같습니다.

카페24 주문 상태 변경 → 웹훅 전송 → 연동 서버 수신 → 데이터 검증 → DB·ERP 업데이트

웹훅을 받은 서버에서는 필요한 정보를 확인한 후 외부 시스템에 전달합니다.

웹훅에서 필요한 주문 정보가 충분하지 않은 경우에는 카페24 주문 상세 API를 추가로 호출해 필요한 데이터를 보완할 수 있습니다.

예를 들어 다음과 같은 정보를 사용할 수 있습니다.

모든 데이터를 무조건 다시 조회하는 것이 아니라 웹훅으로 받은 정보와 필요한 추가 정보만 선택적으로 조회하는 방식으로 구성할 수 있습니다.

웹훅 연동에서는 카페24와 외부 시스템 사이에서 데이터를 받아 처리할 서버가 필요합니다.

구조는 다음과 같습니다.

카페24 → 웹훅 → 연동 서버 → 자체 DB / ERP / 물류 시스템

이 서버에서는 단순히 데이터를 전달하는 것뿐 아니라 여러 가지 작업을 수행할 수 있습니다.

1. 웹훅 데이터 확인

카페24에서 전달된 요청이 정상적인 요청인지 확인합니다.

2. 주문 데이터 변환

카페24의 주문 상태와 ERP의 상태명이 다를 수 있습니다.

예를 들어 카페24의 상태를 ERP에서 사용하는 상태명으로 변경하는 매핑 작업이 필요할 수 있습니다.

3. DB 저장

어떤 주문을 언제 처리했는지 서버 DB에 기록합니다.

4. 외부 시스템 전달

ERP나 자체 운영 시스템에 변경된 주문 상태를 전달합니다.

5. 실패 처리

외부 시스템에서 오류가 발생하면 나중에 다시 처리할 수 있도록 기록합니다.

이 때문에 복잡한 주문 연동에서는 웹훅 자체보다 웹훅을 안전하게 처리하는 서버 구조가 중요합니다.

웹훅 연동에서 중요한 부분 중 하나가 중복 처리 방지입니다.

같은 이벤트가 여러 번 전달될 가능성을 고려해야 합니다.

예를 들어 동일한 주문 상태 변경 알림이 두 번 들어왔는데 서버가 두 번 모두 ERP에 전달하면 중복 데이터가 만들어질 수 있습니다.

이를 방지하기 위해 서버에 처리 기록을 남깁니다.

일반적으로 다음과 같은 값을 기준으로 이미 처리한 이벤트인지 확인합니다.

이처럼 같은 이벤트가 다시 들어와도 실제 작업은 한 번만 수행하도록 만드는 것을 멱등 처리라고 합니다.

외부 ERP나 자체 서버가 일시적으로 응답하지 않을 수도 있습니다.

이때 웹훅을 받은 즉시 실패 처리하고 끝내면 해당 주문 상태가 외부 시스템에서 누락될 수 있습니다.

그래서 실패한 작업을 별도로 기록하고 다시 처리할 수 있도록 구성합니다.

예를 들어 다음과 같이 관리할 수 있습니다.

운영 화면에서 실패한 주문을 확인하고 다시 처리할 수 있도록 만들 수도 있습니다.

이렇게 하면 연동 오류가 발생해도 운영자가 원인을 찾기 쉬워집니다.

여기서 실시간이라는 표현은 주의할 필요가 있습니다.

웹훅은 주문 상태가 변경된 후 이벤트를 전달받는 방식이므로 완전히 동시에 데이터가 변경되는 것을 의미하지는 않습니다.

네트워크 지연이나 서버 처리 시간, 재전송 등의 상황이 발생할 수 있습니다.

따라서 실제 개발에서는 다음과 같이 목표를 잡는 것이 현실적입니다.

주문 상태가 변경되면 외부 시스템에도 최대한 빠르게 반영한다.

즉, 일반적인 배치 조회보다 훨씬 빠르게 반영하면서도 장애나 재전송 상황까지 고려하는 방식입니다.

웹훅에만 의존하면 서버 장애나 네트워크 문제로 이벤트가 누락될 가능성을 고려해야 합니다.

반대로 몇 분마다 모든 주문을 다시 조회하면 API 호출이 많아질 수 있습니다.

그래서 이번 사례에서는 웹훅 + 보완 조회 구조를 사용했습니다.

기본적인 흐름은 다음과 같습니다.

평상시 → 웹훅으로 빠르게 처리

장애 발생 → 누락 가능성이 있는 주문을 조회하여 보완

보완 조회 → 이미 처리한 주문은 다시 반영하지 않음

이렇게 구성하면 웹훅의 빠른 반영과 목록 조회의 보완 기능을 함께 사용할 수 있습니다.

모든 주문 상태와 예외 상황을 처음부터 연동할 필요는 없습니다.

실제 운영에서 자주 사용하고 CS에 영향을 많이 주는 상태부터 정하는 것이 좋습니다.

예를 들면 다음과 같습니다.

이후 필요에 따라 교환, 반품, 부분 취소 등의 상태를 추가할 수 있습니다.

특히 부분 취소나 여러 번의 배송처럼 하나의 주문이 여러 상태로 나뉘는 경우에는 별도의 업무 규칙을 먼저 정해야 합니다.

주문 상태가 변경될 때 외부 시스템도 빠르게 따라가도록 만들면 운영자가 데이터를 다시 확인하는 작업을 줄일 수 있습니다.

예를 들어 배송 상태가 변경되면 ERP나 자체 운영 화면에서도 곧바로 확인할 수 있습니다.

이를 통해 다음과 같은 업무를 줄일 수 있습니다.

특히 주문량이 많아질수록 주문 상태를 확인하고 옮기는 반복 작업을 줄이는 효과가 커질 수 있습니다.

웹훅을 연결한다고 모든 문제가 자동으로 해결되는 것은 아닙니다.

다음 항목을 먼저 정해야 합니다.

주문 상태 매핑

카페24와 ERP의 상태명이 다르면 서로 어떤 상태로 연결할지 정해야 합니다.

중복 처리

같은 웹훅이 여러 번 들어와도 주문이 중복 처리되지 않아야 합니다.

실패 재처리

ERP나 외부 서버의 오류가 발생했을 때 다시 처리할 방법이 필요합니다.

취소 처리

3PL이나 ERP로 주문이 넘어간 후 취소가 발생하면 어떤 방식으로 처리할지 정해야 합니다.

부분 취소

한 주문에서 일부 상품만 취소되는 경우에는 주문 단위가 아니라 상품 단위의 처리가 필요할 수 있습니다.

부분 배송

한 주문이 여러 번 나누어 배송되면 송장과 배송 상태를 관리하는 구조가 복잡해질 수 있습니다.

따라서 처음부터 모든 예외 상황을 구현하기보다 쇼핑몰에서 실제로 사용하는 상태와 업무 흐름을 기준으로 범위를 정하는 것이 중요합니다.

개발이 끝난 후에는 실제 운영 상황과 비슷한 조건으로 테스트해야 합니다.

대표적인 테스트 항목은 다음과 같습니다.

1. 주문 결제

2. 주문 상태 변경

3. 웹훅 수신

4. 외부 시스템 상태 변경

5. 배송 상태 변경

6. 배송 완료

7. 주문 취소

8. 동일 웹훅 중복 수신

9. 외부 시스템 응답 실패

10. 실패한 주문 재처리

11. 웹훅 누락 후 보완 조회

특히 동일한 웹훅을 두 번 보내도 외부 시스템에는 한 번만 반영되는지 확인하는 것이 중요합니다.

그렇지는 않습니다.

주문량이 적고 하루 한 번 엑셀로 데이터를 확인해도 업무에 문제가 없다면 복잡한 웹훅 연동이 필요하지 않을 수 있습니다.

반대로 다음과 같은 상황이라면 웹훅 연동을 검토할 수 있습니다.

중요한 것은 실시간 연동 자체가 아니라 현재 업무에서 발생하는 지연과 반복 작업을 줄이는 것입니다.

옴니어스24는 먼저 현재 주문 처리 과정을 확인합니다.

단순히 주문 상태를 실시간으로 연동해 주세요라는 요구만으로 바로 개발 범위를 정하지 않습니다.

먼저 다음 내용을 확인합니다.

그 결과에 따라 기본 기능, API 조회, 웹훅, 별도 서버, 보완 배치 등의 방법을 나누어 설계합니다.

필요한 부분만 연결하면 불필요하게 복잡한 시스템을 만드는 것도 줄일 수 있습니다.