Webhooks
Les webhooks envoient des notifications en temps réel à vos systèmes externes lorsqu'un événement actif se produit. Utilisez-les avec Zapier, Make, des API personnalisées ou des systèmes d'inventaire.
1. Accéder aux Webhooks
Navigation : Assets → Settings → onglet Webhooks.
2. Créer un Webhook
- Cliquez sur New Webhook
- Entrez le Webhook Name (ex. : "Sync to ERP")
- Entrez l'Webhook URL - votre endpoint (doit accepter les requêtes POST)
- Sélectionnez les Events auxquels vous abonner (ou sélectionnez tous)
- Définissez éventuellement une Secret Key pour la vérification de signature HMAC
- Ajoutez éventuellement des Custom Headers (ex. : clé API)
- Définissez Active sur Yes
- Cliquez sur Save
3. Événements disponibles
Cycle de vie des actifs
| Événement | Quand déclenché |
|---|---|
asset.created | Nouvel actif créé |
asset.updated | Actif mis à jour |
asset.deleted | Actif supprimé |
Allocation et assignation
| Événement | Quand déclenché |
|---|---|
asset.allocated | Actif alloué au personnel |
asset.revoked | Allocation révoquée |
Check-in/Check-out
| Événement | Quand déclenché |
|---|---|
asset.checked_out | Actif checké out |
asset.checked_in | Actif checké in |
Réservations
| Événement | Quand déclenché |
|---|---|
asset.reserved | Réservation créée |
asset.reservation_approved | Réservation approuvée |
asset.reservation_rejected | Réservation rejetée |
Maintenance et transferts
| Événement | Quand déclenché |
|---|---|
asset.maintenance_scheduled | Maintenance programmée |
asset.maintenance_completed | Maintenance terminée |
asset.transferred | Transfert terminé |
Perte, dommage, liquidation
| Événement | Quand déclenché |
|---|---|
asset.lost | Actif déclaré perdu |
asset.broken | Actif déclaré cassé |
asset.warranty | Actif envoyé en garantie |
asset.liquidated | Actif liquidé |
Alertes (via Cron)
| Événement | Quand déclenché |
|---|---|
alert.warranty_expiring | Garantie expire dans 30 jours |
alert.maintenance_due | Maintenance due dans 7 jours |
alert.checkout_overdue | Checkout en retard |
alert.low_stock | Stock sous le seuil |
4. Format du payload
Chaque webhook envoie un payload JSON :
{
"event": "asset.created",
"timestamp": "2025-02-04T12:00:00+00:00",
"source": "perfex_assets_module",
"asset_id": 123,
"asset": { ... },
"data": { ... }
}
- event - Nom de l'événement
- timestamp - Format ISO 8601
- asset_id - ID de l'actif (null si supprimé)
- asset - Données de l'actif (ou données supplémentaires pour supprimé)
- data - Données spécifiques à l'événement (ex. : détails d'allocation)
5. Vérification de signature
Le module envoie une signature HMAC-SHA256 dans l'en-tête :
X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>
Vérifiez dans votre endpoint :
signature = HMAC-SHA256(secret_key, request_body)
6. Webhook Logs
- Consultez les Webhook Logs pour voir le statut des livraisons
- Response Code - 2xx = succès, 4xx/5xx = échec
- Retry - Certaines interfaces permettent de réessayer les livraisons échouées
- Les logs sont généralement nettoyés après 30 jours
7. Tester le Webhook
Utilisez Test Webhook pour envoyer un payload de test. Utile pour vérifier que votre endpoint est accessible et correctement configuré.
Bonnes pratiques
- Utilisez HTTPS pour les URLs webhook
- Vérifiez la signature pour garantir que les requêtes proviennent du module
- Répondez rapidement (ex. : 200 OK) - timeout environ 30 secondes
- Gérez les doublons - le même événement peut être renvoyé
- Surveillez les logs pour les livraisons échouées