Skip to main content
웹훅은 주문 처리가 완료되거나 실패할 때 서버에 HTTP POST 콜백을 전달합니다. 주문 조회 엔드포인트를 반복 폴링하는 대신 웹훅을 사용하면 결과가 준비되는 즉시 알림을 받을 수 있습니다.

웹훅 설정

1

웹훅 엔드포인트 등록

API 또는 BIZ MORI 대시보드에서 웹훅 엔드포인트를 생성할 수 있습니다. 이 예제는 live API 키로 live 엔드포인트를 생성합니다. API를 통해 생성하려면 웹훅 생성 엔드포인트를 사용합니다:
응답:
secret을 즉시 저장하세요 — 한 번만 표시되며 다시 조회할 수 없습니다. 모든 수신 웹훅 서명 검증에 필요합니다.
2

엔드포인트 구현

웹훅 핸들러는 다음을 수행해야 합니다:
  • JSON 본문으로 POST 요청을 수락
  • 5초 이내2xx 상태 코드로 응답
  • 처리 전 X-MoriBiz-Signature 헤더 검증
3

서명 검증

모든 요청에는 X-MoriBiz-Signature 헤더가 포함됩니다. 사용 중인 언어의 구현은 아래 서명 검증을 참고하세요.

테스트 웹훅

테스트 주문 이벤트를 받으려면 Dashboard, 일반 API 키 또는 테스트 API 키로 별도의 테스트 endpoint를 등록하세요. 테스트 키는 isTest를 생략하거나 true로 지정할 수 있고, isTest: falseAUTH_FORBIDDEN을 반환합니다.
  • 테스트 API 키는 같은 owner의 테스트 endpoint만 생성·목록·상세·수정·삭제할 수 있고, 해당 endpoint의 이벤트 조회와 실패 이벤트 재전송을 할 수 있습니다. live 모드와 다른 owner의 리소스는 노출되지 않습니다.
  • isTest: true endpoint는 테스트 주문 이벤트만 받습니다.
  • isTest: false endpoint는 운영 주문 이벤트만 받습니다.
  • 테스트 웹훅도 일반 웹훅과 동일한 이벤트명, HMAC-SHA256 서명, timeout, 재시도 정책을 사용합니다.
  • 테스트 처리는 결과 파일을 만들지 않으므로 Anti-AI와 워터마크 삽입 이벤트의 downloadUrlnull입니다.
테스트 endpoint CRUD, 이벤트 목록, 재전송에는 아래의 owner 및 테스트 모드 격리가 동일하게 적용됩니다.

이벤트 유형

웹훅 페이로드

모든 웹훅 페이로드는 다음 구조를 따릅니다:

완료 이벤트 — 공통 필드

실패 이벤트 — 공통 필드

Anti-AI / 워터마크 삽입 — 추가 필드 (완료)

워터마크 추출 — 추가 필드 (완료)

status 필드는 항상 complete입니다. 워터마크 감지 여부는 statusCode로 확인하세요. 페이로드는 텍스트만 공개하며 MID, midDecimal, midHex는 포함하지 않습니다.

AI Detection — 추가 필드 (완료)

서명 검증

X-MoriBiz-Signature 헤더를 확인하여 웹훅 진위를 검증합니다. 이벤트 처리 전에 반드시 검증하세요.

재시도 정책

BIZ MORI는 안정적인 웹훅 전송을 보장하기 위해 다단계 재시도 시스템을 사용합니다.

초기 재시도

엔드포인트가 2xx 상태 코드를 반환하지 않으면 BIZ MORI가 즉시 재시도합니다:

스케줄러 기반 재시도

초기 재시도가 모두 실패하면, 이벤트는 점차 간격이 늘어나는 스케줄러 기반 재시도 큐에 등록됩니다: 스케줄러 기반 재시도가 모두 소진되면 이벤트가 FAILED로 표시됩니다. 웹훅 이벤트 목록 엔드포인트를 사용하여 실패한 이벤트를 확인할 수 있습니다.

수동 재전송 API

자동 재시도 프로세스와 관계없이, 재전송 API를 통해 언제든지 수동으로 웹훅을 재전송할 수 있습니다:
  • 단일 이벤트 재전송: POST /api/v2/orders/webhooks/{webhookId}/events/{eventId}/retry를 사용하여 특정 실패 이벤트를 재시도합니다.
  • 일괄 재전송: POST /api/v2/orders/webhooks/{webhookId}/events/retry-failed를 사용하여 특정 기간(최대 7일) 내 실패한 모든 이벤트를 재시도합니다.

실패 알림 이메일

초기 웹훅 전송이 실패하면 계정 소유자에게 웹훅 전송 실패 알림 이메일을 발송합니다. 과도한 알림을 방지하기 위해 이 이메일은 하루 최대 1회만 발송됩니다.

웹훅 관리

테스트 API 키 범위

테스트 API 키는 같은 owner의 테스트 엔드포인트만 관리할 수 있습니다. 해당 엔드포인트의 목록·상세·등록·수정·삭제와 이벤트 목록, 실패한 단일 이벤트 재전송, 최대 7일 범위의 실패 이벤트 일괄 재전송을 할 수 있습니다. 이벤트 응답에는 전송 로그의 응답 본문이 추가되지 않습니다.
  • 등록 시 isTest를 생략하거나 true로 지정하면 테스트 엔드포인트가 생성됩니다. isTest: falseAUTH_FORBIDDEN을 반환합니다.
  • 수정 시 isTest를 생략하면 테스트 모드를 유지하고, true는 허용됩니다. isTest: falseAUTH_FORBIDDEN을 반환합니다.
  • live 엔드포인트 ID 또는 다른 owner의 엔드포인트 ID는 WEBHOOK_NOT_FOUND를 반환하며, 존재 여부를 공개하지 않습니다.
  • 접근 가능한 엔드포인트에 속하지 않은 이벤트 ID는 WEBHOOK_EVENT_NOT_FOUND를 반환합니다.
live API 키와 Dashboard는 기존처럼 isTest를 선택하고 owner의 live·test 엔드포인트를 관리할 수 있습니다. secret 일회성 표시, URL 검증, HMAC 서명, 재시도 정책은 변경되지 않습니다.