콘텐츠로 이동
사용 가이드
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

웹훅은 박스히어로에서 특정 이벤트가 발생했을 때, 해당 정보를 실시간으로 외부 시스템에 전달하는 연동 방식입니다.

Webhook 등록

섹션 제목: “Webhook 등록”

설정 > 연동 설정 메뉴에서 웹훅을 등록할 수 있습니다.

Webhook 핸들러

섹션 제목: “Webhook 핸들러”

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

이벤트 본문

섹션 제목: “이벤트 본문”

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

{
  "id": "1234", // 이벤트의 고유 ID
  "topic": "txs/new", // 이벤트 주제
  "version": 1, // 이벤트 본문의 버전
  "payload": { // 이벤트 본문
    ...
  },
  "created_time": "2024-08-06T09:20:48.623Z" // 이벤트 발생 시간
}

이벤트 순서

섹션 제목: “이벤트 순서”

박스히어로는 이벤트의 전달 순서를 보장하지 않습니다.

예를 들어, item/new 이벤트가 item/delete 이벤트 이후에 도착할 수 있습니다. 이벤트 본문의 created_time 필드는 이벤트 실제 발생 시각을 의미하므로, 이를 활용해 적절히 처리될 수 있도록 직접 구현해 주세요.

이벤트 주제

섹션 제목: “이벤트 주제”

필요한 주제가 있다면 고객센터로 문의해주세요.

txs/new

섹션 제목: “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.from_location_new_stock_level재고 변동 이후, 출발 위치에서의 재고 수량
items.to_location_new_stock_level✓재고 변동 이후, 도착 위치에서의 재고 수량
transaction_time✓트랜잭션 시점(e.g. 입/출고 시간)
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",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "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
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "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"
}

txs/edit

섹션 제목: “txs/edit”

기존 재고 변동 내역(입고,출고,조정,이동)이 수정되었을 때 발송됩니다.

필드명필수 여부설명
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.from_location_new_stock_level재고 변동 이후, 출발 위치에서의 재고 수량
items.to_location_new_stock_level✓재고 변동 이후, 도착 위치에서의 재고 수량
transaction_time✓트랜잭션 시점(e.g. 입/출고 시간)
created_at✓재고 변동 내역이 작성된 시점
created_by✓재고 변동 내역을 작성한 멤버
created_by.id✓멤버의 고유 ID
created_by.name✓멤버의 이름
created_by.deleted✓탈퇴한 멤버 여부
count_of_items✓제품별 항목수
total_quantity✓재고 변동량의 총합
url✓재고 변동 상세 내역 페이지로 이동할 수 있는 주소
memo메모
reivison✓재고 변동 내역의 현재 버전. 1부터 시작합니다.

이벤트 본문 예시 : 입고 내역이 수정

섹션 제목: “이벤트 본문 예시 : 입고 내역이 수정”
{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "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
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "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"
}

txs/delete

섹션 제목: “txs/delete”

재고 변동 내역이 삭제되었을 때 발송됩니다.

필드명설명
id재고 변동 내역의 고유 ID
revision재고 변동 내역의 현재 버전. 1부터 시작합니다.

이벤트 본문 예시

섹션 제목: “이벤트 본문 예시”
{
  "id": 27036740,
  "revision": 2
}

item/new

섹션 제목: “item/new”

제품이 추가되었을 때 발송됩니다.

필드명설명
id제품의 고유 ID
name제품명
skusku
barcode바코드
photo_url제품 사진 URL
cost구매가
price판매가
attrs제품 속성 데이터

이벤트 본문 예시

섹션 제목: “이벤트 본문 예시”
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2024-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

섹션 제목: “item/edit”

제품이 수정되었을 때 발송됩니다.

필드명설명
id제품의 고유 ID
name제품명
skuSKU
barcode바코드
photo_url제품 사진 URL
cost구매가
price판매가
attrs제품 속성 데이터

이벤트 본문 예시

섹션 제목: “이벤트 본문 예시”
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2024-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

섹션 제목: “item/delete”

제품이 삭제되었을 때 발송됩니다.

필드명설명
id제품의 고유 ID

이벤트 본문 예시

섹션 제목: “이벤트 본문 예시”
{
  "id": 26122826
}