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

엑셀로 제품을 대량 추가하거나 수정한 경우 생성되는 조정 내역에 대해서는 발송되지 않습니다.

새롭게 재고 변동 내역(입고/출고/조정/이동)이 작성되었을 때 발송됩니다.

이벤트 본문 예시 - 입고 이벤트가 발생함

{
  "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

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

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

{
  "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

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

필드명

설명

재고 변동 내역의 고유 ID

revision

재고 변동 내역의 현재 버전. 1부터 시작합니다.

이벤트 본문 예시

{
  "id": 27036740,
  "revision": 2
}

item/new

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

현재 옵션 일괄 추가 / 엑셀 대량 추가 기능 사용시에는 발송되지 않습니다.

필드명

설명

제품의 고유 ID

name

제품명

sku

거래처

barcode

거래처의 고유 ID

photo_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

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

현재 엑셀 대량 수정 혹은 [데이터 관리] > [제품]에서의 대량 수정 기능 사용시에는 발송되지 않습니다.

필드명

설명

제품의 고유 ID

name

제품명

sku

거래처

barcode

거래처의 고유 ID

photo_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

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

현재 [데이터 관리] > [제품]에서의 대량 삭제 기능 사용시에는 발송되지 않습니다.

필드명

설명

제품의 고유 ID

이벤트 본문 예시

{
  "id": 26122826
}

Last updated 12 days ago