Webhooks
当资产事件发生时，Webhooks 会向外部系统发送实时通知。可与 Zapier、Make、自定义 API 或库存系统配合使用。
1. 访问 Webhooks
导航： Assets → Settings → Webhooks 选项卡。
2. 创建 Webhook
- 点击 New Webhook
- 输入 Webhook Name（例如 "Sync to ERP"）
- 输入 Webhook URL - 您的端点（必须接受 POST 请求）
- 选择要订阅的 Events（或全选）
- 可选：设置 Secret Key 用于 HMAC 签名验证
- 可选：添加 Custom Headers（例如 API key）
- 将 Active 设为 Yes
- 点击 Save
3. 可用事件
资产生命周期
| Event | When Triggered |
|---|---|
asset.created | New asset created |
asset.updated | Asset updated |
asset.deleted | Asset deleted |
分配与指派
| Event | When Triggered |
|---|---|
asset.allocated | Asset allocated to staff |
asset.revoked | Allocation revoked |
签入/签出
| Event | When Triggered |
|---|---|
asset.checked_out | Asset checked out |
asset.checked_in | Asset checked in |
预订
| Event | When Triggered |
|---|---|
asset.reserved | Reservation created |
asset.reservation_approved | Reservation approved |
asset.reservation_rejected | Reservation rejected |
维护与转移
| Event | When Triggered |
|---|---|
asset.maintenance_scheduled | Maintenance scheduled |
asset.maintenance_completed | Maintenance completed |
asset.transferred | Transfer completed |
丢失、损坏、处置
| Event | When Triggered |
|---|---|
asset.lost | Asset reported lost |
asset.broken | Asset reported broken |
asset.warranty | Asset sent for warranty |
asset.liquidated | Asset liquidated |
警报（通过 Cron）
| Event | When Triggered |
|---|---|
alert.warranty_expiring | Warranty expiring in 30 days |
alert.maintenance_due | Maintenance due in 7 days |
alert.checkout_overdue | Checkout overdue |
alert.low_stock | Stock below threshold |
4. 有效负载格式
每个 webhook 发送 JSON 有效负载：
{
"event": "asset.created",
"timestamp": "2025-02-04T12:00:00+00:00",
"source": "perfex_assets_module",
"asset_id": 123,
"asset": { ... },
"data": { ... }
}
- event - Event name
- timestamp - ISO 8601 format
- asset_id - ID of the asset (null for deleted)
- asset - Asset data (or extra data for deleted)
- data - Event-specific data (e.g., allocation details)
5. 签名验证
模块在请求头中发送 HMAC-SHA256 签名：
X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>
在您的端点中验证：
signature = HMAC-SHA256(secret_key, request_body)
6. Webhook 日志
- 查看 Webhook Logs 了解发送状态
- Response Code - 2xx = 成功，4xx/5xx = 失败
- Retry - 部分接口允许重试失败的发送
- 日志通常在 30 天后清理
7. 测试 Webhook
使用 Test Webhook 发送测试有效负载。用于验证您的端点可访问且配置正确。
最佳实践
- 使用 HTTPS 作为 webhook URL
- 验证签名 以确保持有来自模块的请求
- 快速响应（例如 200 OK）- 超时约 30 秒
- 处理重复 - 同一事件可能被重试
- 监控日志 以发现发送失败