Webhook（出站）

Webhook 是集成中的「推送」一侧：无需您的系统轮询 FreeMaint，事件一旦发生，FreeMaint 就会向您的 URL 发起 POST。在「公司设置 > Webhook」（/company-settings/webhooks）中配置。Starter 套餐起可用（每天 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 — 每家公司每天一份汇总，列出处于再订货点或以下的备件，包括从未发生过出入库的备件
part.out_of_stock_summary — 同一份每日汇总，针对库存为零的备件
part.consumed — 备件在工单上被消耗，或被退回
compliance.chain_divergence — 审计哈希链断裂（Enterprise）
asset.downtime_started — 开启了一次设备停机
asset.downtime_ended — 关闭了一次设备停机；现在可以核算时长
report.daily_summary — 当天已完成的工作，每天一次，时间由你设定
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 在重试和重发之间保持不变：把它当作幂等键，同一笔出库就永远不会被重复入账。当数据双向流动时有一点务必知晓：GraphQL 的 adjustStock 变更不会触发该事件。这是有意为之——您自己的系统写入 FreeMaint 的库存更正，绝不应作为回声返回给您并被重复入账。只有在 FreeMaint 内部记录在工单上的消耗才会触发 part.consumed。零件还带有 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，并附带 X-FreeMaint-Signature 头，格式为 t=<unix 秒>,v1=<十六进制>，其中 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" 数组：最多 4 个指向 JPG、PNG、GIF 或 WebP 图片的 HTTPS 链接，最新的优先。每个链接在 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 —— 每家公司每天 100 次投递
Business —— 不限量
Enterprise —— 不限量
计数按投递尝试计：三个 webhook 订阅同一事件即消耗三次
每日计数在 00:00 UTC 重置

提示

请对每个请求校验 X-FreeMaint-Signature 头（针对原始主体），以免伪造的调用在您的 ERP 中变动库存。