توثيق ربط الـ API

Headers

Content-Type: application/json
X-Najmat-Event: attendance.check_in
X-Najmat-Signature: <hmac_sha256_hex_of_body>

Body (مثال حدث حضور)

{
  "event": "attendance.check_in",
  "timestamp": "2026-07-19T08:15:32.000Z",
  "data": {
    "employee_id": "EMP-001",
    "employee_name": "محمد أحمد",
    "user_id": "uuid...",
    "check_in_time": "2026-07-19T08:15:32.000Z",
    "location": { "lat": 24.71, "lng": 46.68 },
    "is_late": false,
    "late_minutes": 0
  }
}

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

التحقق من التوقيع (Node.js)

import { createHmac, timingSafeEqual } from 'crypto';

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-najmat-signature'];
  const body = JSON.stringify(req.body);
  const expected = createHmac('sha256', process.env.NAJMAT_WEBHOOK_SECRET)
    .update(body).digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).send('Invalid signature');
  }

  // معالجة الحدث
  console.log('Event:', req.body.event, req.body.data);
  res.send('ok');
});

التحقق من التوقيع (PHP)

$signature = $_SERVER['HTTP_X_NAJMAT_SIGNATURE'];
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('NAJMAT_WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature)) {
  http_response_code(401); exit;
}
$payload = json_decode($body, true);

ممارسات موصى بها

• ارجع HTTP 2xx خلال 10 ثوانٍ — أي شيء آخر يُعتبر فشلاً
• عالج الحدث في queue خلفية بدل معالجة مباشرة
• خزّن event.id لتفادي المعالجة المكررة (idempotency)
• لا تعتمد على ترتيب الأحداث — استخدم timestamp