コンテンツにスキップ
ユーザーガイド
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

Webhookは、BoxHeroで特定のイベントが発生したときにリアルタイムで通知を受け取れる機能です。

登録

Section titled “登録”

Webhookは、BoxHeroチームの設定 > 連携設定で登録できます。

送信と再試行の仕組み

Section titled “送信と再試行の仕組み”

イベントが発生すると、BoxHeroは登録されたWebhookエンドポイントにHTTP POST リクエストを送信します。リクエストボディには、イベントの内容を表すJSONペイロードが含まれます。

  • サーバーが 2xxステータスコード (例: 200, 201, 204) で応答した場合、送信は成功として扱われます。
  • 2xx以外の応答 は失敗とみなされ、再試行されます。

Webhookペイロードの構造

Section titled “Webhookペイロードの構造”

すべてのWebhookイベントは、リクエストボディに次のJSON構造で送信されます。

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}

イベントの順序

Section titled “イベントの順序”

BoxHeroはイベントの送信順序を 保証しません 。たとえば、同じ商品について item/new イベントが item/delete イベントより後に届く場合があります。

イベントペイロードの created_time フィールドは、実際にイベントが発生した日時を表します。イベントを確実に処理するため、Webhookハンドラーには冪等性があり、順序の入れ替わりに対応できるロジックを実装してください。

イベントトピック

Section titled “イベントトピック”

txs/new

Section titled “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✓トランザクション日時（例: 入庫・出庫日時）
created_at✓トランザクションが作成された日時
created_by✓トランザクションを作成したメンバー
created_by.id✓メンバーの固有ID
created_by.name✓メンバー名
created_by.deleted✓メンバーが削除されているかどうか
count_of_items✓商品数
total_quantity✓在庫変動量の合計
url✓トランザクション詳細ページを表示するURL
memoトランザクションに関するメモ

Webhookペイロードの例 – Stock In イベント

Section titled “Webhookペイロードの例 – Stock In イベント”
{
  "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"
}

Webhookペイロードの例 – Move Stock イベント

Section titled “Webhookペイロードの例 – Move Stock イベント”
{
  "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": "2025-04-25T05:42:27.545Z",
  "created_at": "2025-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Tony Lee",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/edit

Section titled “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✓トランザクション日時（例: 入庫・出庫日時）
created_at✓トランザクションが作成された日時
created_by✓トランザクションを作成したメンバー
created_by.id✓メンバーの固有ID
created_by.name✓メンバー名
created_by.deleted✓メンバーが削除されているかどうか
count_of_items✓商品数
total_quantity✓在庫変動量の合計
url✓トランザクション詳細ページを表示するURL
memoトランザクションに関するメモ
revision✓トランザクションの現在のバージョン番号（1から始まります）

Webhookペイロードの例 – 編集された Stock In トランザクション

Section titled “Webhookペイロードの例 – 編集された Stock In トランザクション”
{
  "id": 16160911,
  "revision": 2,
  "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"
}

Webhookペイロードの例 – 編集された Move Stock トランザクション

Section titled “Webhookペイロードの例 – 編集された Move Stock トランザクション”
{
  "id": 3692714,
  "revision": 2,
  "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

Section titled “txs/delete”

在庫トランザクションが 削除 されたときに送信されます。

フィールド説明
idトランザクションの固有ID
revisionトランザクションの現在のバージョン番号（1から始まります）

Webhookペイロードの例 – 削除されたトランザクション

Section titled “Webhookペイロードの例 – 削除されたトランザクション”
{
  "id": 27036740,
  "revision": 2
}

item/new

Section titled “item/new”

チームの在庫に新しい商品が追加されたときに送信されます。

フィールド説明
id商品ID
name商品名
skuSKU
barcodeバーコード
photo_url写真URL
cost原価
price販売価格
attrs属性

ペイロードの例 – 商品の作成

Section titled “ペイロードの例 – 商品の作成”
{
  "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": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Section titled “item/edit”

既存の商品が編集されたときに送信されます。

フィールド説明
id商品ID
name商品名
skuSKU
barcodeバーコード
photo_url写真URL
cost原価
price販売価格
attrs属性

ペイロードの例 – 商品の更新

Section titled “ペイロードの例 – 商品の更新”
{
  "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": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Section titled “item/delete”

チームの在庫から商品が削除されたときに送信されます。

フィールド説明
id商品ID

ペイロードの例 – 商品の削除

Section titled “ペイロードの例 – 商品の削除”
{
  "id": 26122826
}