Webhooks
Os webhooks enviam notificações em tempo real para seus sistemas externos quando ocorrem eventos de ativos. Use-os com Zapier, Make, APIs personalizadas ou sistemas de inventário.
1. Acessar Webhooks
Navegação: Assets → Settings → aba Webhooks.
2. Criar um Webhook
- Clique em New Webhook
- Insira o Webhook Name (ex.: "Sync to ERP")
- Insira a Webhook URL – seu endpoint (deve aceitar requisições POST)
- Selecione os Events para assinar (ou selecione todos)
- Opcionalmente defina Secret Key para verificação de assinatura HMAC
- Opcionalmente adicione Custom Headers (ex.: API key)
- Defina Active como Yes
- Clique em 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. Verificação de Assinatura
O módulo envia uma assinatura HMAC-SHA256 no header:
X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>
Verifique no seu endpoint:
signature = HMAC-SHA256(secret_key, request_body)
6. Logs de Webhook
- Visualize Webhook Logs para ver o status de entrega
- Response Code – 2xx = sucesso, 4xx/5xx = falha
- Retry – Algumas interfaces permitem repetir entregas falhas
- Os logs são normalmente limpos após 30 dias
7. Test Webhook
Use Test Webhook para enviar uma carga de teste. Útil para verificar se seu endpoint está acessível e configurado corretamente.
Melhores Práticas
- Use HTTPS para URLs de webhook
- Verify signature para garantir que as requisições sejam do módulo
- Respond quickly (ex.: 200 OK) – o timeout é de ~30 segundos
- Handle duplicates – o mesmo evento pode ser tentado novamente
- Monitor logs para entregas falhas