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. Webhooks aufrufen

Navigation: Assets → Settings → Webhooks-Tab.

---

2. Create a Webhook

1. Click New Webhook
2. Enter Webhook Name (e.g., "Sync to ERP")
3. Enter Webhook URL - your endpoint (must accept POST requests)
4. Select Events to subscribe to (or select all)
5. Optionally set Secret Key for HMAC signature verification
6. Optionally add Custom Headers (e.g., API key)
7. Set Active to Yes
8. 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>

Verifizieren Sie in Ihrem Endpunkt:

signature = HMAC-SHA256(secret_key, request_body)

---

6. Webhook-Logs

• Webhook Logs anzeigen, um den Lieferstatus zu sehen
• Response Code – 2xx = Erfolg, 4xx/5xx = Fehler
• Retry – Einige Oberflächen ermöglichen erneute Zustellversuche bei Fehlern
• Logs werden typischerweise nach 30 Tagen bereinigt

---

7. Test Webhook

Verwenden Sie Test Webhook, um eine Test-Nutzlast zu senden. Nützlich, um zu überprüfen, ob Ihr Endpunkt erreichbar und korrekt konfiguriert ist.

---

Best Practices

• Use HTTPS für Webhook-URLs
• Verify signature, um sicherzustellen, dass Anfragen vom Modul stammen
• Respond quickly (z. B. 200 OK) – Timeout beträgt ca. 30 Sekunden
• Handle duplicates – dasselbe Event kann erneut versendet werden
• Monitor logs für fehlgeschlagene Zustellungen