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

1. Clique em New Webhook
2. Insira o Webhook Name (ex.: "Sync to ERP")
3. Insira a Webhook URL – seu endpoint (deve aceitar requisições POST)
4. Selecione os Events para assinar (ou selecione todos)
5. Opcionalmente defina Secret Key para verificação de assinatura HMAC
6. Opcionalmente adicione Custom Headers (ex.: API key)
7. Defina Active como Yes
8. 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