Webhooks

ترسل Webhooks إشعارات فورية إلى أنظمتك الخارجية عند حدوث أحداث الأصول. استخدمها مع Zapier أو Make أو واجهات API المخصصة أو أنظمة المخزون.

---

1. الوصول إلى Webhooks

التنقل: Assets → Settings → تبويب Webhooks.

---

2. إنشاء Webhook

1. انقر على New Webhook
2. أدخل Webhook Name (مثال: "Sync to ERP")
3. أدخل Webhook URL - نقطة النهاية الخاصة بك (يجب أن تقبل طلبات POST)
4. حدد Events للمشاركة فيها (أو حدد الكل)
5. اختيارياً: حدد Secret Key للتحقق من توقيع HMAC
6. اختيارياً: أضف Custom Headers (مثال: API key)
7. اضبط Active على Yes
8. انقر على Save

---

3. الأحداث المتاحة

دورة حياة الأصل

Event	When Triggered
asset.created	New asset created
asset.updated	Asset updated
asset.deleted	Asset deleted

التخصيص والتعيين

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

الحجوزات

Event	When Triggered
asset.reserved	Reservation created
asset.reservation_approved	Reservation approved
asset.reservation_rejected	Reservation rejected

الصيانة والنقل

Event	When Triggered
asset.maintenance_scheduled	Maintenance scheduled
asset.maintenance_completed	Maintenance completed
asset.transferred	Transfer completed

الفقدان والتلف والتخلص

Event	When Triggered
asset.lost	Asset reported lost
asset.broken	Asset reported broken
asset.warranty	Asset sent for warranty
asset.liquidated	Asset liquidated

التنبيهات (عبر 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. صيغة الحمولة

كل webhook يرسل حمولة JSON:

{
  "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. التحقق من التوقيع

ترسل الوحدة توقيع HMAC-SHA256 في الرأس:

X-Asset-Webhook-Signature: <signature>
X-Asset-Webhook-Timestamp: <timestamp>
X-Asset-Webhook-Event: <event>

تحقق في نقطة النهاية الخاصة بك:

signature = HMAC-SHA256(secret_key, request_body)

---

6. سجلات Webhook

• اعرض Webhook Logs لرؤية حالة التسليم
• Response Code - 2xx = نجاح، 4xx/5xx = فشل
• Retry - تسمح بعض الواجهات بإعادة محاولة التسليم الفاشل
• تُنظف السجلات عادةً بعد 30 يوماً

---

7. اختبار Webhook

استخدم Test Webhook لإرسال حمولة اختبار. مفيد للتحقق من أن نقطة النهاية لديك قابلة للوصول ومُكوّنة بشكل صحيح.

---

أفضل الممارسات

• استخدم HTTPS لعناوين URL الخاصة بـ webhooks
• تحقق من التوقيع للتأكد من أن الطلبات من الوحدة
• رد بسرعة (مثال: 200 OK) - الوقت المهلة ~30 ثانية
• تعامل مع التكرارات - قد تُعاد محاولة نفس الحدث
• راقب السجلات للتسليمات الفاشلة