Webhooks
Webhooks send real-time notifications to your external systems when asset events occur. Use them with Zapier, Make, custom APIs, or inventory systems.
1. Access Webhooksโ
Navigation: Assets โ Settings โ Webhooks tab.
2. Create a Webhookโ
- Click New Webhook
- Enter Webhook Name (e.g., "Sync to ERP")
- Enter Webhook URL - your endpoint (must accept POST requests)
- Select Events to subscribe to (or select all)
- Optionally set Secret Key for HMAC signature verification
- Optionally add Custom Headers (e.g., API key)
- Set Active to Yes
- Click Save
3. Available Eventsโ
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. Payload Formatโ
Each webhook sends a JSON payload:
{
"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. Signature Verificationโ
The module sends an HMAC-SHA256 signature in the header:
X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>
Verify in your endpoint:
signature = HMAC-SHA256(secret_key, request_body)
6. Webhook Logsโ
- View Webhook Logs to see delivery status
- Response Code - 2xx = success, 4xx/5xx = failure
- Retry - Some interfaces allow retrying failed deliveries
- Logs are typically cleaned after 30 days
7. Test Webhookโ
Use Test Webhook to send a test payload. Useful to verify your endpoint is reachable and correctly configured.
Best Practicesโ
- Use HTTPS for webhook URLs
- Verify signature to ensure requests are from the module
- Respond quickly (e.g., 200 OK) - timeout is ~30 seconds
- Handle duplicates - same event may be retried
- Monitor logs for failed deliveries