Webhooks
Los Webhooks envían notificaciones en tiempo real a tus sistemas externos cuando ocurren eventos de activos. Úsalos con Zapier, Make, APIs personalizadas o sistemas de inventario.
1. Acceder a Webhooks
Navegación: Assets → Settings → pestaña Webhooks.
2. Crear un Webhook
- Haz clic en New Webhook
- Introduce el Webhook Name (p. ej., "Sync to ERP")
- Introduce el Webhook URL - tu endpoint (debe aceptar peticiones POST)
- Selecciona los Events a los que suscribirse (o selecciona todos)
- Opcionalmente configura Secret Key para verificación de firma HMAC
- Opcionalmente añade Custom Headers (p. ej., API key)
- Establece Active en Yes
- Haz clic en Save
3. Eventos disponibles
Ciclo de vida del activo
| Event | When Triggered |
|---|---|
asset.created | Nuevo activo creado |
asset.updated | Activo actualizado |
asset.deleted | Activo eliminado |
Asignación y asignación
| Event | When Triggered |
|---|---|
asset.allocated | Activo asignado al personal |
asset.revoked | Asignación revocada |
Check-in/Check-out
| Event | When Triggered |
|---|---|
asset.checked_out | Activo objeto de check-out |
asset.checked_in | Activo objeto de check-in |
Reservas
| Event | When Triggered |
|---|---|
asset.reserved | Reserva creada |
asset.reservation_approved | Reserva aprobada |
asset.reservation_rejected | Reserva rechazada |
Mantenimiento y transferencias
| Event | When Triggered |
|---|---|
asset.maintenance_scheduled | Mantenimiento programado |
asset.maintenance_completed | Mantenimiento completado |
asset.transferred | Transferencia completada |
Pérdida, daño, disposición
| Event | When Triggered |
|---|---|
asset.lost | Activo reportado como perdido |
asset.broken | Activo reportado como roto |
asset.warranty | Activo enviado a garantía |
asset.liquidated | Activo liquidado |
Alertas (vía Cron)
| Event | When Triggered |
|---|---|
alert.warranty_expiring | Garantía expira en 30 días |
alert.maintenance_due | Mantenimiento debido en 7 días |
alert.checkout_overdue | Checkout vencido |
alert.low_stock | Stock por debajo del umbral |
4. Formato del payload
Cada webhook envía un payload JSON:
{
"event": "asset.created",
"timestamp": "2025-02-04T12:00:00+00:00",
"source": "perfex_assets_module",
"asset_id": 123,
"asset": { ... },
"data": { ... }
}
- event - Nombre del evento
- timestamp - Formato ISO 8601
- asset_id - ID del activo (null si está eliminado)
- asset - Datos del activo (o datos extra si está eliminado)
- data - Datos específicos del evento (p. ej., detalles de asignación)
5. Verificación de firma
El módulo envía una firma HMAC-SHA256 en el encabezado:
X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>
Verifica en tu endpoint:
signature = HMAC-SHA256(secret_key, request_body)
6. Registros de Webhooks
- Consulta Webhook Logs para ver el estado de entrega
- Response Code - 2xx = éxito, 4xx/5xx = fallo
- Retry - Algunas interfaces permiten reintentar entregas fallidas
- Los registros suelen limpiarse tras 30 días
7. Probar Webhook
Usa Test Webhook para enviar un payload de prueba. Útil para verificar que tu endpoint es accesible y está configurado correctamente.
Buenas prácticas
- Usa HTTPS para las URLs de webhooks
- Verifica la firma para asegurarte de que las peticiones provienen del módulo
- Responde rápidamente (p. ej., 200 OK) - el timeout es de ~30 segundos
- Maneja duplicados - el mismo evento puede reintentarse
- Monitorea los registros para entregas fallidas