Webhooks
Webhooks は資産イベント発生時に外部システムへリアルタイムで通知を送信します。Zapier、Make、カスタム API、在庫システムで使用できます。
1. Webhooks にアクセスする
ナビゲーション： Assets → Settings → Webhooks タブ。
2. Webhook を作成する
- New Webhook をクリック
- Webhook Name を入力（例：「Sync to ERP」）
- Webhook URL を入力 - エンドポイント（POST リクエストを受け付ける必要あり）
- 購読する Events を選択（またはすべて選択）
- オプションで HMAC 署名検証用の Secret Key を設定
- オプションで Custom Headers を追加（例：API key）
- Active を Yes に設定
- Save をクリック
3. 利用可能なイベント
Asset Lifecycle
| Event | When Triggered |
|---|---|
asset.created | New asset created |
asset.updated | Asset updated |
asset.deleted | Asset deleted |
Allocation & Assignment
| Event | When Triggered |
|---|---|
asset.allocated | Asset allocated to staff |
asset.revoked | Allocation revoked |
Check-in/Check-out
| Event | When Triggered |
|---|---|
asset.checked_out | Asset checked out |
asset.checked_in | Asset checked in |
Reservations
| Event | When Triggered |
|---|---|
asset.reserved | Reservation created |
asset.reservation_approved | Reservation approved |
asset.reservation_rejected | Reservation rejected |
Maintenance & Transfers
| Event | When Triggered |
|---|---|
asset.maintenance_scheduled | Maintenance scheduled |
asset.maintenance_completed | Maintenance completed |
asset.transferred | Transfer completed |
Loss, Damage, Disposal
| Event | When Triggered |
|---|---|
asset.lost | Asset reported lost |
asset.broken | Asset reported broken |
asset.warranty | Asset sent for warranty |
asset.liquidated | Asset liquidated |
Alerts (via 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 でテストペイロードを送信できます。エンドポイントが到達可能で正しく設定されているか確認するのに便利です。
ベストプラクティス
- Webhook URL には HTTPS を使用
- リクエストがモジュールからのものであることを確認するため 署名を検証
- 迅速に応答（例：200 OK）- タイムアウトは約 30 秒
- 重複を処理 - 同じイベントが再試行される場合がある
- 失敗した配信のため ログを監視