웹훅(Webhook)

웹훅은 박스히어로에서 특정한 이벤트가 발생하였을 때, 실시간으로 알림을 받아볼 수 있는 기능입니다.

Webhook 등록

[결제 및 설정] - [외부 서비스 연동 & API] 메뉴에서 웹훅을 등록할 수 있습니다.

Webhook 핸들러

이벤트 발생시 등록된 Webhook Endpoint로 이벤트 본문을 전달합니다. webhook 핸들러 응답 status code가 200인 경우 정상적으로 수신하였다고 판단합니다. 만약 200이 아닌 status code가 반환되는 경우 일시적 에러로 간주하여 최대 3번까지 재시도 합니다.

이벤트 본문

이벤트 전달시 POST Body에 아래 데이터를 JSON 형태로 포함하여 전달합니다.

{
  "id": "1234", // 이벤트의 고유 ID
  "topic": "txs/new", // 이벤트 주제
  "version": 1, // 이벤트 본문의 버전
  "payload": { // 이벤트 본문
    ...
  }
}

이벤트 주제

현재 txs/new 이벤트만 지원하고 있습니다. 추가로 필요한 주제가 있다면 고객센터([e-mail])로 요청주세요.

txs/new

재고 변동(입고/출고/조정/이동) 이벤트가 발생하였을때 발송됩니다.

필드명	필수 여부	팀 모드	설명
id		공통	히스토리의 고유 ID
type		공통	히스토리의 유형 (입고->in, 출고->out, 조정->adjust, 이동->move)
partner		공통	거래처
partner.id		공통	거래처의 고유 ID
partner.name		공통	거래처의 이름
partner.deleted		공통	삭제된 거래처 여부
from_location		위치	출발 위치
from_location.id		위치	위치의 고유 ID
from_location.name		위치	위치명
from_location.deleted		위치	삭제된 위치 여부
to_location		위치	도착 위치
to_location.id		위치	위치의 고유 ID
to_location.name		위치	위치명
to_location.deleted		위치	삭제된 위치 여부
items		공통	히스토리의 제품별 항목
items.id		공통	제품의 고유 ID
items.name		공통	제품명
items.quantity		공통	입고/출고/조정/이동에 의한 재고의 변경량
items.deleted		공통	제품의 삭제 여부
items.new_stock_level		기본/유닛	히스토리가 반영된 이후의 재고 수량
items.from_location_new_stock_level		위치	히스토리가 반영된 이후, 출발 위치에서의 재고 수량
items.to_location_new_stock_level		위치	히스토리가 반영된 이후, 도착 위치에서의 재고 수량
created_at		공통	히스토리가 생성된 시점
created_by		공통	히스토리를 생성한 멤버
created_by.id		공통	멤버의 고유 ID
created_by.name		공통	멤버의 이름
created_by.deleted		공통	탈퇴한 멤버 여부
count_of_items		공통	제품별 항목수
total_quantity		공통	재고 변동량의 총합
url		공통	히스토리 상세정보 페이지로 이동할 수 있는 주소
memo		공통	메모

예시 - 기본모드 팀에서 입고 이벤트가 발생함

{
  "id": 16160911,
  "type": "in",
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "new_stock_level": 40
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "new_stock_level": 207
    }
  ],
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

예시 - 위치모드 팀에서 이동 이벤트가 발생함

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}