Documentation Index Fetch the complete documentation index at: https://docs.bizmori.com/llms.txt
Use this file to discover all available pages before exploring further.
웹훅은 주문 처리가 완료되거나 실패할 때 서버에 HTTP POST 콜백을 전달합니다. 주문 조회 엔드포인트를 반복 폴링하는 대신 웹훅을 사용하면 결과가 준비되는 즉시 알림을 받을 수 있습니다.
웹훅 설정
웹훅 엔드포인트 등록
API 또는 BIZ MORI 대시보드 에서 웹훅 엔드포인트를 생성할 수 있습니다. API를 통해 생성하려면 웹훅 생성 엔드포인트를 사용합니다: curl -X POST https://api.bizmori.com/api/v2/orders/webhooks \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "내 웹훅", "url": "https://your-server.com/webhook" }'
응답: { "data" : { "id" : 1 , "name" : "내 웹훅" , "secret" : "whsec_xxxxxxxxxxxxxxxxxx" } }
secret을 즉시 저장하세요 — 한 번만 표시되며 다시 조회할 수 없습니다. 모든 수신 웹훅 서명 검증에 필요합니다.
엔드포인트 구현
웹훅 핸들러는 다음을 수행해야 합니다:
JSON 본문으로 POST 요청을 수락
5초 이내 에 2xx 상태 코드로 응답처리 전 X-MoriBiz-Signature 헤더 검증
서명 검증
모든 요청에는 X-MoriBiz-Signature 헤더가 포함됩니다. 사용 중인 언어의 구현은 아래 서명 검증 을 참고하세요. 이벤트 유형 이벤트 유형 설명 order.antiAi.completedAnti-AI 처리 성공 완료 order.antiAi.failedAnti-AI 처리 실패 order.watermarkEmbed.completed워터마크 삽입 성공 완료 order.watermarkEmbed.failed워터마크 삽입 실패 order.watermarkExtract.completed워터마크 추출 성공 완료 order.watermarkExtract.failed워터마크 추출 실패 order.aiDetection.completedAI Detection 성공 완료 order.aiDetection.failedAI Detection 실패
웹훅 페이로드 모든 웹훅 페이로드는 다음 구조를 따릅니다:
{ "eventId" : "550e8400-e29b-41d4-a716-446655440000" , "eventType" : "order.antiAi.completed" , "occurredAt" : "2026-02-19T12:00:00.000Z" , "data" : { "orderId" : "123456789" , "orderName" : "anti_ai_2026-02-19" , "createdAt" : "2026-02-19T11:50:00.000Z" , "updatedAt" : "2026-02-19T12:00:00.000Z" , "completedAt" : "2026-02-19T12:00:00.000Z" , "status" : "complete" // ...각 기능 별 추가 필드 } }
완료 이벤트 — 공통 필드 필드 타입 설명 orderIdstring 주문 ID orderNamestring 주문명 createdAtstring 주문 생성 시간 (ISO 8601) updatedAtstring 주문 최종 업데이트 시간 (ISO 8601) completedAtstring 처리 완료 시간 (ISO 8601) statusstring 항상 complete
실패 이벤트 — 공통 필드 필드 타입 설명 orderIdstring 주문 ID orderNamestring 주문명 createdAtstring 주문 생성 시간 (ISO 8601) updatedAtstring 주문 최종 업데이트 시간 (ISO 8601) failedAtstring 처리 실패 시간 (ISO 8601) statusstring 항상 failed errorCodestring 오류 코드 errorMessagestring 오류 메시지
Anti-AI / 워터마크 삽입 — 추가 필드 (완료) 필드 타입 설명 fileCountinteger 처리된 파일 수 downloadUrlstring 결과 파일 다운로드 URL (1시간 유효)
워터마크 추출 — 추가 필드 (완료) status 필드는 항상 complete입니다. 워터마크 감지 여부는 statusCode로 확인하세요.필드 타입 설명 statusCodestring detected 또는 undetectedwatermarkFoundboolean 워터마크 감지 여부 watermarkInfo.textstring 감지된 워터마크 텍스트 (watermarkFound가 true일 때만)
AI Detection — 추가 필드 (완료) 필드 타입 설명 probabilitynumber AI 생성 확률 (0.0–1.0) heatmapUrlstring | null AI 판별 히트맵 이미지 다운로드 URL (generateHeatmap 옵션 사용 시에만 반환) overlayUrlstring | null 원본 위 히트맵 오버레이 이미지 다운로드 URL (generateOverlay 옵션 사용 시에만 반환)
서명 검증 X-MoriBiz-Signature 헤더를 확인하여 웹훅 진위를 검증합니다. 이벤트 처리 전에 반드시 검증하세요.Node.js
Python
PHP
Ruby
Go
Java
const crypto = require ( 'crypto' ); function verifyWebhookSignature ( rawBody , signature , secret ) { const expected = crypto . createHmac ( 'sha256' , secret ) . update ( rawBody ) // 원시 요청 바디 문자열 사용 . digest ( 'hex' ); return crypto . timingSafeEqual ( Buffer . from ( signature ), Buffer . from ( expected ) ); } // Express 핸들러 app . post ( '/webhook' , express . raw ({ type: 'application/json' }), ( req , res ) => { const signature = req . headers [ 'x-moribiz-signature' ]; if ( ! verifyWebhookSignature ( req . body . toString (), signature , process . env . WEBHOOK_SECRET )) { return res . status ( 401 ). send ( 'Invalid signature' ); } const { eventType , data } = JSON . parse ( req . body ); console . log ( `주문 ${ data . orderId } 의 ${ eventType } 이벤트 수신` ); res . sendStatus ( 200 ); });
재시도 정책 BIZ MORI는 안정적인 웹훅 전송을 보장하기 위해 다단계 재시도 시스템을 사용합니다.
초기 재시도 엔드포인트가 2xx 상태 코드를 반환하지 않으면 BIZ MORI가 즉시 재시도합니다:
시도 지연 1차 재시도 1초 2차 재시도 2초 3차 재시도 4초
스케줄러 기반 재시도 초기 재시도가 모두 실패하면, 이벤트는 점차 간격이 늘어나는 스케줄러 기반 재시도 큐에 등록됩니다:
시도 지연 4차 재시도 30분 5차 재시도 2시간 6차 재시도 4시간
스케줄러 기반 재시도가 모두 소진되면 이벤트가 FAILED로 표시됩니다. 웹훅 이벤트 목록 엔드포인트를 사용하여 실패한 이벤트를 확인할 수 있습니다.
수동 재전송 API 자동 재시도 프로세스와 관계없이, 재전송 API를 통해 언제든지 수동으로 웹훅을 재전송할 수 있습니다:
# 단일 이벤트 재전송 curl -X POST https://api.bizmori.com/api/v2/orders/webhooks/{webhookId}/events/{eventId}/retry \ -H "Authorization: Bearer YOUR_API_TOKEN" # 특정 기간 내 실패한 이벤트 일괄 재전송 curl -X POST https://api.bizmori.com/api/v2/orders/webhooks/{webhookId}/events/retry-failed \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fromDate": "2026-01-01", "toDate": "2026-01-07" }'
실패 알림 이메일 초기 웹훅 전송이 실패하면 계정 소유자에게 웹훅 전송 실패 알림 이메일을 발송합니다. 과도한 알림을 방지하기 위해 이 이메일은 하루 최대 1회 만 발송됩니다.
웹훅 관리 
