> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/ja/integrations/webhook.md).

# Webhook

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

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## 登録

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

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

## 送信と再試行の仕組み

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

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

## Webhookペイロードの構造

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

```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)
}
```

---

## イベントの順序

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

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

## イベントトピック

> **Note**
>
> 追加のイベントトピックへの対応が必要な場合は、[お問い合わせ](https://www.boxhero.io/docs/ja/resources/contact)までご連絡ください。

### txs/new

在庫トランザクション（入庫 / 出庫 / 調整 / 移動）が発生したときに送信されます。

> **Caution**
>
> **注意:** 一括編集やインポート（例: Excelで商品を追加・更新した場合）によって作成された調整では、このイベントは _送信されません_ 。

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| 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 イベント

```json
{
  "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 イベント

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

既存の在庫トランザクション（入庫 / 出庫 / 移動 / 調整）が **編集** されたときに送信されます。

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| 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 トランザクション

```json
{
  "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 トランザクション

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

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

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

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

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

### item/new

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

> **Caution**
>
> **注意**: `オプションを一括追加` 機能を使用した場合や、`Excelを読み込み` で商品をインポートした場合、このイベントは _送信されません_ 。

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

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

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

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

> **Caution**
>
> **注意**: `データ管理` > `商品` での一括編集や、`Excelを読み込み` 機能による編集では、このイベントは _送信されません_ 。

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

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

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

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

> **Caution**
>
> **注意**: `データ管理` > `商品` での一括削除では、このイベントは _送信されません_ 。

| フィールド | 説明 |
| --- | --- |
| id | 商品ID |

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

```json
{
  "id": 26122826
}
```