Webhook（送信）

Webhook は連携の「プッシュ」側です。自社システムが FreeMaint を問い合わせるのではなく、何かが起きた時点で FreeMaint があなたの URL へ POST します。設定は「会社設定 > Webhook」（/company-settings/webhooks）から。Starter プラン以上で利用できます（1 日 100 配信、Business 以上は無制限）。

利用できるイベント

work_order.created — 作業指示が作成された
work_order.completed — 作業指示が「完了」になった
work_order.status_changed — 作業指示がいずれかのステータスへ遷移した。ペイロードに new_status を含む。変更のない work_order.completed と併せて発火する
request.created — 保全依頼が送信された
request.status_changed — 依頼が承認・却下・取消された
part.low_stock — 部品が発注点以下になった
part.out_of_stock — 部品が在庫ゼロになった
part.low_stock_summary — 会社ごとに 1 日 1 通のまとめ。発注点以下の部品を、一度も動いていない部品も含めて列挙する
part.out_of_stock_summary — 在庫ゼロの部品を対象とした、同じ日次まとめ
part.consumed — 部品が作業指示で消費された、または返却された
compliance.chain_divergence — 監査ハッシュチェーンが途切れた（Enterprise）
asset.downtime_started — 設備停止が開始された
asset.downtime_ended — 設備停止が終了した。停止時間を計上できる
report.daily_summary — その日に完了した作業を、指定した時刻に 1 日 1 回
purchase_order.created — 発注書が作成されました。ペイロードには発注書（reference、status、total_cost、currency、expected_date、erp_reference）と仕入先が含まれます
purchase_order.status_changed — 発注書のステータスが変わりました（承認、発注済み、取消など）。ペイロードには previous_status と new_status が含まれます
purchase_order.received — 発注書に対する納品を受領しました（一部納品を含め、納品のたびに送信）。ペイロードは各明細を quantity_ordered、quantity_received（今回の納品）、quantity_received_total、quantity_remaining 付きで列挙し、receipt_id、fully_received、closed_short も含みます。入荷待ちが残る間 new_status は PARTIALLY_RECEIVED、完了または締めた時点で RECEIVED になります

part.consumed — 在庫を ERP に反映する

別のシステム（ERP、請求、在庫、会計）に、保全で実際に使用した部品を反映させる必要がある場合に購読すべきイベントです。quantity は符号付きで、部品が作業に払い出されたときは負、作業指示から取り除かれて返却されたときは正になります。そのため、FreeMaint 側での取消は、連携先でも対応する取消伝票を生成します。stock_movement_id は再試行や再送をまたいでも変わりません。これを冪等キーとして使えば、同じ払い出しを二重に計上することはありません。データが双方向に流れる場合に知っておくべき点が 1 つあります。GraphQL の adjustStock ミューテーションはこのイベントを発生させません。これは意図的なもので、ご自身のシステムが FreeMaint に書き込んだ在庫補正が、エコーとして戻ってきて二重に計上されることがあってはならないためです。part.consumed が発生するのは、FreeMaint 内で作業指示に記録された消費だけです。部品には custom_reference も含まれます。これはお客様独自の部品コード（createPart または updatePart で設定した customReference）で、カタログを管理するシステムは FreeMaint の ID 対応表なしで各行を照合できます。

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "ベアリング 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "個" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "ベアリング交換" }, "asset": { "id": 91, "name": "セパレーター 2" }, "location": { "id": 7, "name": "工場倉庫" }, "user": { "id": 5627, "name": "技術者 A" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

配信と署名

各配信は JSON ボディの POST で、t=<unix 秒>,v1=<16 進> 形式の X-FreeMaint-Signature ヘッダーが付きます。v1 は Webhook シークレットを鍵として文字列「<t>.<生ボディ>」を HMAC-SHA256 したものです。JSON のパースや再シリアライズより前に、生ボディに対して検証してください。X-FreeMaint-Event と X-FreeMaint-Delivery-Id も送信します。2xx なら配信成功とみなします。ネットワークエラーと 5xx は指数バックオフで最大 3 回まで再試行します（約 2 秒、4 秒、8 秒）。4xx は恒久的な拒否として扱い、再試行しません。

配信の再送

各試行はステータスと応答コードとともに、その Webhook の配信履歴に残ります。完了した配信はそこから再送できます。保存済みのペイロードがそのまま再送されるため、中の業務キー（stock_movement_id を含む）は変わらず、正しく重複排除する受信側が二重計上することはありません。エンドポイントが停止していたときや、誤ってリクエストを拒否したときは、これで取り戻します。

写真（任意）

Webhook で「写真を含める」がオンの場合（初期設定ではオフ）、"work_order" と "request" のオブジェクトに "photos" 配列が含まれます。JPG、PNG、GIF、WebP 画像への HTTPS リンクが新しい順に最大 4 件です。各リンクは 7 日間ログインなしで画像を開けるため、それ以上必要な場合はファイルをご自身のシステムに保存してください。再送では同じリンクが送られます。その他のイベントや Webhook は変わりません。 "work_order.created" と "request.created" では、「写真を含める」がオンの Webhook はイベントの 90 秒後に送信されます（"timestamp" フィールドはイベントの時刻のままです）。レコードの直後にアップロードされた写真も含めるためです。

URL の要件

https:// のみ — 平文の http は拒否されます
ポートは 443 または 8443 のみ
ホストは公開到達可能であること — ループバック、プライベート、CGNAT の範囲は拒否されます
URL に認証情報を含めないこと（https://user:pass@host は拒否されます）
社内ネットワークにしか存在しないシステムには、公開エンドポイントか中継（n8n、Make、Zapier）が必要です

上限

Starter — 1 社あたり 1 日 100 配信
Business — 無制限
Enterprise — 無制限
カウントは配信試行ごと。同じイベントを購読する Webhook が 3 つあれば 3 単位を消費します
日次カウンターは 00:00 UTC にリセットされます

ヒント

すべてのリクエストで X-FreeMaint-Signature ヘッダーを生ボディに対して検証し、なりすましの呼び出しが ERP の在庫を動かせないようにしてください。