Webhooks 概要

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

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

Webhook の種類

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

	Source Inventory	Routing Allocation	Routing Cancel	Fulfillment Status	Oversell Status	Order Update
トリガー	在庫取込の成功直後	Routing のルーティング完了直後	Routing Cancel のキャンセル確定直後	Fulfillment の status 更新直後	Oversell Cases の warehouse_received 遷移直後	Address Recovery の住所修正成功直後
送信条件	合算値が前回送信値と異なる 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 と同じテンプレートエンジン）。

• 変数差し込み: 文字列内の {{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 と共有）。レスポンス・読み取り 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 を参照。

次のステップ

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