出站 Webhooks

Webhook 让 FreeMaint 在事件发生的瞬间向您掌控的 URL 发起 POST，从而让另一套系统（ERP、开票、库存、财务、聊天频道）保持同步，无需任何人重复录入。在 /company-settings/webhooks 中配置。Starter 每天上限 100 次投递；Business 及以上不限量。完整的载荷参考见「API 与 GraphQL > Webhook」。

可订阅的事件

• work_order.created — 创建了工单
• work_order.completed — 工单变为「已完成」
• work_order.status_changed — 工单切换到任意状态；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 — 创建了一张采购订单
• purchase_order.status_changed — 采购订单状态发生变化（已批准、已下单、已取消……）
• purchase_order.received — 采购订单收到了一次到货，包括部分到货

投递语义

• POST，JSON 主体：{ event, timestamp, data }
• X-FreeMaint-Signature 头 —— t=<unix 秒>,v1=<十六进制>，其中 v1 是以您的 webhook 密钥为键、对「<t>.<原始主体>」计算的 HMAC-SHA256。请在每个请求中针对原始主体校验
• 同时发送 X-FreeMaint-Event 与 X-FreeMaint-Delivery-Id
• 网络错误和 5xx 最多重试 3 次并采用指数退避（约 2 秒、4 秒、8 秒）；4xx 视为永久拒绝，不再重试
• 每次尝试都会记录在该 webhook 下，含状态、响应码和尝试次数——任何已结束的投递都可从那里重发
• 可选照片：开启“包含照片”后，"work_order" 和 "request" 事件会在 "photos" 字段中携带最多 4 个图片链接，任何持有者在 7 天内均可打开——仅对您控制的端点开启

配置步骤

1. 打开 /company-settings/webhooks — 需要公司设置权限或“管理集成”权限。
2. 点击「添加 Webhook」 — 填写名称、https:// URL，并勾选所需事件。
3. 复制签名密钥 — 创建时只显示一次。之后可通过「轮换密钥」生成新的，旧密钥随即失效。
4. 查看投递记录 — 打开该 webhook 的投递历史，确认事件送达，并重发失败的记录。

各套餐配额

• Starter —— 每家公司每天 100 次投递（计数在 00:00 UTC 重置）
• Business —— 不限量
• Enterprise —— 不限量
• 计数按投递尝试计：同一事件上的三个 webhook 消耗三次