> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/webhooks/overview.md).

# Webhooks 概要

LMile 側で発生した変化（在庫変動・引き当て暫定確定・確保前キャンセル・出荷ステータス遷移・受注情報更新）を、登録した宛先 URL へ HTTP POST で通知します。ポーリングなしで EC・WMS・基幹システムを LMile の最新状態に同期できます。

> **Base URL** `https://api.lmile.io` · **認証** `x-ingest-secret` ヘッダー（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` はリクエストボディに含めます（省略するとキーのアカウント）

## Webhook の種類

| Webhook                                                          | 通知するイベント                                    | 設定エンドポイント                                          | 設定単位（upsert キー）                 |
| ---------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------- | ------------------------------- |
| [Source Inventory](/lmile-docs/webhooks/source-inventory.md)     | 出荷元の合算販売可能在庫が barcode 単位で変動                 | `POST /api/routing/source-webhook-config`          | `shop` × 出荷元ロケーション              |
| [Routing Allocation](/lmile-docs/webhooks/allocation.md)         | ルーティングで在庫引き当てが暫定確定                          | `POST /api/routing/allocation-webhook-config`      | `shop`                          |
| [Routing Cancel](/lmile-docs/webhooks/order-cancelled.md)        | 確保前の注文キャンセル（確保前の引き当てを取消）                    | （Routing Allocation の設定を再利用・別途登録不要）                | `shop`                          |
| [Fulfillment Status](/lmile-docs/webhooks/fulfillment-status.md) | 出荷元（shipment）の出荷ステータスが遷移                    | `POST /api/routing/status-webhook-config`          | `shop`（× 任意で取込元 `sourceSystem`） |
| [Oversell Status](/lmile-docs/webhooks/oversell-status.md)       | 売越しケースが MFC 倉庫受付完了（`warehouse_received`）に遷移 | `POST /api/routing/oversell-status-webhook-config` | `shop`                          |
| [Order Update](/lmile-docs/webhooks/order-update.md)             | 受注情報の更新（当面は配送先住所の手修正）                       | `POST /api/routing/order-update-webhook-config`    | `shop`                          |

|          | Source Inventory                                           | Routing Allocation                                                           | Routing Cancel                                                        | Fulfillment Status                                                                         | Oversell Status                                                                       | Order Update                                                                  |
| -------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| トリガー     | [在庫取込](/lmile-docs/ingestion-api/inventory-levels.md)の成功直後 | [Routing](/lmile-docs/routing-api/orders.md) のルーティング完了直後                     | [Routing Cancel](/lmile-docs/routing-api/cancel-update.md) のキャンセル確定直後 | [Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md) の status 更新直後                    | [Oversell Cases](/lmile-docs/oversell-api/cases.md) の `warehouse_received` 遷移直後       | [Address Recovery](/lmile-docs/fulfillment-api/address-recovery.md) の住所修正成功直後 |
| 送信条件     | 合算値が**前回送信値と異なる** barcode のみ                               | 引き当て先ロケーションごとに 1 通 + 引き当て不能明細があれば `unallocated` 1 通                          | **確保前**（`secured_at IS NULL`）・未出荷の shipment ごとに 1 通                   | **直前と異なる** status になった shipment のみ（初回含む）                                                   | ケースが `warehouse_received` に遷移したとき 1 通（1 ケース = 1 単位）                                   | 住所修正が成功するたびに 1 通（1 修正 = 1 通）                                                  |
| 既定イベント名  | `fulfillment_source_inventory_changed`                     | `routing_allocation_decided`                                                 | `routing_order_cancelled`                                             | `fulfillment_shipment_status_changed`                                                      | `oversell_case_warehouse_received`                                                    | `order_update`                                                                |
| ペイロードの性質 | 合算在庫の**絶対値**（差分ではない）                                       | 引き当て結果の**絶対状態**（`allocationStatus` / `fromLocationId` + 明細 snapshot `lines`） | キャンセルの相関情報（`shipmentId` 中心・明細なし）                                      | 遷移後の**絶対状態**（`status` / `previousStatus` / `trackingNumber`）+ 出荷明細（`shipmentId` / `lines`） | 受付完了の**絶対状態**（`status: warehouse_received` / `foundLocationId` + 明細 snapshot `lines`） | 修正後の**絶対状態**（`changeType` / 修正後 `shipTo` snapshot。**PII を含む**）                |
| outbox   | `sot.lm_fulfillment_source_inventory_events`               | `sot.lm_routing_allocation_events`                                           | `sot.lm_routing_cancel_events`                                        | `sot.lm_fulfillment_status_events`                                                         | `sot.lm_oversell_status_events`                                                       | `sot.lm_order_update_events`                                                  |

いずれも絶対値・絶対状態を送るため、受け手は重複受信があっても冪等に上書きできます。

## 共通の仕組み

これらの webhook は設定スキーマ・テンプレートエンジン・配信機構を共有します（Routing Cancel は専用の設定を持たず Routing Allocation の設定を再利用します）。

### 設定（upsert）

設定エンドポイントへの `POST` で登録・更新します。同じキーへの再 POST は上書き（upsert）、無効化は `isActive: false` を送ります。

共通パラメータ:

| パラメータ             | 型            |  必須 | 説明                                                                                            |
| ----------------- | ------------ | :-: | --------------------------------------------------------------------------------------------- |
| `shop`            | string       |     | 店舗ドメイン（省略するとキーのアカウント）                                                                         |
| `destinationUrl`  | string       |  ✓  | 送信先 webhook エンドポイント。`https://` で始まるホスト名の URL のみ（IP アドレス・`localhost`・`.internal`・`.local` は不可） |
| `payloadTemplate` | object/array |     | 送信ボディのテンプレート（下記）。省略時は各 webhook の既定テンプレート                                                      |
| `httpMethod`      | string       |     | HTTP メソッド（default `POST`）                                                                     |
| `contentType`     | string       |     | `Content-Type`（default `application/json`）                                                    |
| `authType`        | string       |     | `none` / `bearer` / `header`（default `none`）                                                  |
| `authHeaderName`  | string       |     | `authType=header` のときのヘッダー名                                                                   |
| `authSecret`      | string       |     | 認証 secret（暗号化保存。省略時は既存維持）                                                                     |
| `isActive`        | boolean      |     | 有効フラグ（default `true`）                                                                         |

レスポンスに secret 値は返りません（保存済かを示す `has_secret` のみ）。

### ペイロードテンプレート

`payloadTemplate` の JSON を再帰的に描画して送信ボディを組み立てます（[Dispatch Config](/lmile-docs/configuration/dispatch-config.md) と同じテンプレートエンジン）。

* **変数差し込み**: 文字列内の `{{path}}` を値に置換。文字列全体が単一 `{{path}}` の場合は値の型を保持（数値などをそのまま渡す）
* 利用できる変数と既定テンプレートは各 webhook のページを参照

### 配信とリトライ

* **バックグラウンド送信**: トリガー元 API の成功直後に送信し、API レスポンスを遅延させません。送信失敗もトリガー元 API のレスポンスには影響しません
* **認証付き送信**: `authType` に応じて `bearer`（`Authorization: Bearer ...`）/ `header`（任意ヘッダー）を付与
* **リトライ**: 5xx・ネットワークエラーは指数バックオフで最大 2 回再試行

### 耐久性（outbox）

イベントは送信前に outbox テーブルへ起票され、`request_payload`（描画後・secret なし）/ `http_status` / `delivery_status`（`pending` / `sent` / `failed` / `skipped`）/ `attempts` / `last_error` が記録されます。送信前にプロセスが落ちても `pending` / `failed` のイベントは後から回収・再送できます。設定が無い場合は `skipped` を記録します（silent skip しません）。

### secret の取り扱い

`authSecret` は pgcrypto で暗号化して保存します（鍵は Supabase Vault 管理、[Dispatch Config](/lmile-docs/configuration/dispatch-config.md) と共有）。レスポンス・読み取り view・送信ログのいずれにも平文 secret は出ません。

## エラー

設定エンドポイント共通:

| Status | 条件                                                                                   | レスポンス例                                                                                               |
| :----: | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
|  `400` | JSON でない / ボディがオブジェクトでない                                                             | `{ "ok": false, "error": "body must be a JSON object" }`                                             |
|  `422` | 必須欠落・不正値（`error_kind: invalid_payload`）                                              | `{ "ok": false, "error_kind": "invalid_payload", "error": "destinationUrl required" }`               |
|  `422` | `destinationUrl` が https でない・IP アドレスや内部向けのホスト（`error_kind: invalid_destination_url`） | `{ "ok": false, "error_kind": "invalid_destination_url", "error": "destinationUrl must use https" }` |

認証・メソッド等の共通エラーは [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## 次のステップ

1. [Source Inventory Webhook](/lmile-docs/webhooks/source-inventory.md) — 在庫変動通知の設定・ペイロード
2. [Routing Allocation Webhook](/lmile-docs/webhooks/allocation.md) — 引き当て暫定確定通知の設定・ペイロード
3. [Routing Cancel Webhook](/lmile-docs/webhooks/order-cancelled.md) — 確保前キャンセル通知（Routing Allocation の設定を再利用）
4. [Fulfillment Status Webhook](/lmile-docs/webhooks/fulfillment-status.md) — 出荷ステータス通知の設定・ペイロード
5. [Oversell Status Webhook](/lmile-docs/webhooks/oversell-status.md) — 売越しケース受付完了通知の設定・ペイロード
6. [Order Update Webhook](/lmile-docs/webhooks/order-update.md) — 受注情報更新（住所修正など）通知の設定・ペイロード


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lmile.gitbook.io/lmile-docs/webhooks/overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.