웹훅 가이드

웹훅(Webhook)을 통해 주문 상태 변경, 정산 생성 등 주요 이벤트를 실시간으로 수신할 수 있습니다.

웹훅 개요

웹훅은 브라이트몰 시스템에서 특정 이벤트가 발생했을 때, 입점사가 등록한 URL로 HTTP POST 요청을 보내는 방식입니다.

폴링(주기적 조회) 방식과 비교했을 때 다음과 같은 장점이 있습니다.

방식	특징
폴링 (주기적 API 호출)	불필요한 API 호출 발생, 실시간성 떨어짐, Rate Limit 소모
웹훅 (이벤트 수신)	이벤트 발생 시에만 호출, 실시간 처리, API 호출 최소화

웹훅은 개발자 콘솔 또는 API를 통해 관리할 수 있습니다.

개발자 콘솔의 Webhooks 메뉴에서 웹훅을 등록, 수정, 삭제할 수 있습니다. UI를 통해 직관적으로 관리하는 것을 권장합니다.

프로그래밍 방식으로 웹훅을 관리해야 하는 경우 다음 API를 사용합니다.

기능	엔드포인트	설명
목록 조회	`GET /vendor-api/webhooks`	등록된 웹훅 목록 조회
등록	`POST /vendor-api/webhooks`	새 웹훅 엔드포인트 등록
수정	`PUT /vendor-api/webhooks/:id`	기존 웹훅 수정
삭제	`DELETE /vendor-api/webhooks/:id`	웹훅 삭제
테스트	`POST /vendor-api/webhooks/:id/ping`	웹훅 연결 테스트
이벤트 목록	`GET /vendor-api/webhooks/events`	구독 가능한 이벤트 타입 조회

API 상세 명세는 다음 페이지를 참조하세요:

웹훅을 등록할 때 다음 정보를 설정합니다.

웹훅 URL은 반드시 HTTPS를 사용해야 합니다. HTTP URL은 등록이 거부됩니다.

브라이트몰은 이벤트 발생 시 등록된 URL로 다음과 같은 HTTP POST 요청을 보냅니다.


POST {등록된 웹훅 URL}
Content-Type: application/json

웹훅 수신 후 반드시 HTTP 200 상태 코드를 반환해야 합니다. 200 이외의 응답이나 타임아웃이 발생하면 재시도합니다.

웹훅 전송 실패 시 지수 백오프(exponential backoff) 방식으로 재시도합니다. 일정 횟수 이상 연속 실패하면 해당 웹훅이 자동 비활성화될 수 있습니다.

수신한 웹훅이 브라이트몰에서 발송한 것인지 검증하려면 요청 헤더의 서명값을 확인합니다. 검증 방법의 상세 내용은 개발자 콘솔의 Webhooks 설정 페이지에서 확인할 수 있습니다.

웹훅을 등록한 후 정상적으로 수신되는지 확인하려면 ping API를 사용합니다.


POST /vendor-api/webhooks/:id/ping

테스트 이벤트가 등록된 URL로 전송되며, 수신 결과를 응답으로 확인할 수 있습니다.