MIJI DApp Server Docs

Webhook Event Guide

서버는 Bull webhook-queue를 통해 외부 엔드포인트로 비동기 이벤트를 전달합니다. 모든 요청은 POST 메서드로 JSON Payload를 전송하며, Body에는 항상 eventType 필드가 포함됩니다.

공통 헤더

Header	설명
Content-Type	application/json
x-webhook-event	이벤트 이름 (deployment.success, mint.failed 등)
x-webhook-secret	WEBHOOK_SECRET가 설정된 경우 서명 토큰 전달

이벤트 종류

Event Type (Header/Body)	설명	Payload 주요 필드 (항상 eventType 포함)
deployment.success	컨트랙트 배포 성공	contractId, chainId, ercStandard, name, symbol, contractAddress, txHash, metadataBaseUri, contractType
deployment.failed	컨트랙트 배포 실패	contractId, chainId, ercStandard, name, symbol, error, contractType
mint.confirmed	민팅 성공	orderId, metadataId, chainId, contractAddress, receiverAddress, tokenId, amount, txHash, contractType, metadataHash, tokenUri
mint.failed	민팅 실패	orderId, metadataId, chainId, contractAddress, receiverAddress, tokenId, amount, error, contractType, metadataHash, tokenUri
transfer.success	Transfer 성공	orderId, chainId, contractAddress, from, to, tokenId, amount, txHash, ercStandard
transfer.failed	Transfer 실패	orderId, chainId, contractAddress, from, to, tokenId, error
ownership.transferred	소유권 이전 성공	contractId, chainId, contractAddress, previousOwner, newOwner, txHash, gasUsed
ownership.failed	소유권 이전 실패	contractId, chainId, contractAddress, newOwner, error

모든 이벤트는 동일한 형식의 헤더(x-webhook-event)와 Body(eventType)를 전달하므로 두 값이 서로 일치합니다.

예시 Payload (transfer.success)

{
  "eventType": "transfer.success",
  "orderId": "692e84f3d3e3deac5d7f7ba6",
  "chainId": "43113",
  "contractAddress": "0x9e9b178cf24bd802dfbdd97435c94e9289f9a91e",
  "from": "0x08a02c036fadcaf5c47a6b1a4a26a19bf71c18e7",
  "to": "0x5a6be23be47d5dd4e1d3324a6b8c2975c910165f",
  "tokenId": "111",
  "amount": 1,
  "txHash": "0x092d18e28cef3cb7a90fe2ae44164f6f2a2f8631639c6f3f37e1a9f72d31d7c1",
  "ercStandard": "721"
}

응답이 2xx가 아닐 경우 Bull 기본 재시도 정책(최대 5회, 지수 백오프 10초 기준)이 적용됩니다. 재시도 상태는 MongoDB WebhookLog 컬렉션에서 확인할 수 있습니다.