أحداث تصلك بنفسها

الأحداث

تسعة أنواع أحداث تُرسل اليوم، تغطي دورة حياة الفاتورة وتغييرات العملاء.

الحمولة

التسليمات هي POST بصيغة JSON تحمل اسم الحدث ولقطة المورد ومعرف مؤسستك ووقت الإصدار:

POST https://example.ma/hisab-webhook
Content-Type: application/json
X-Webhook-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-Webhook-Timestamp: 1780750800
X-Webhook-Event: invoice.paid
X-Webhook-Delivery-Id: del_3f8c2a91
User-Agent: Hisab-Webhooks/1.0

{
  "event": "invoice.paid",
  "data": {
    "id": "inv_8f3a91",
    "invoice_number": "FAC-2026-0142",
    "status": "paid",
    "total": "12480.00"
  },
  "organization_id": "org_4d11a7",
  "created_at": "2026-06-05T14:00:00Z"
}

التوقيعات

كل تسليم موقع بسر نقطتك: HMAC-SHA256 على الطابع الزمني ثم نقطة ثم الجسم الخام. تحقق دائماً قبل الوثوق بالحمولة.

import { verifyWebhookSignature } from 'hisab-sdk';

export async function POST(req: Request) {
  const payload = await req.text();

  const valid = verifyWebhookSignature({
    payload,
    signature: req.headers.get('x-webhook-signature')!,
    timestamp: req.headers.get('x-webhook-timestamp')!,
    secret: process.env.HISAB_WEBHOOK_SECRET!,
  });

  if (!valid) return new Response('Invalid signature', { status: 401 });
  return new Response('ok');
}

إعادة المحاولات

ينجح التسليم بأي استجابة 2xx خلال 30 ثانية. غير ذلك يعاد حتى 5 مرات بمهل متزايدة:

تحمل المهل نحو 20% من العشوائية (jitter) فالأوقات الدقيقة تتغير. بعد الفشل الخامس يوسم التسليم فاشلاً؛ يمكنك إعادة تشغيله يدوياً من لوحة التحكم.

ممارسات جيدة

• تحقق من كل توقيع

  ارفض كل ما يفشل في التحقق. فهو لم يأتِ من حساب.

• استجب بسرعة

  أكّد بـ 2xx قبل أي معالجة ثقيلة؛ ينتهي وقت التسليم بعد 30 ثانية.

• أزل التكرار بمعرف التسليم

  تعيد المحاولات استخدام ترويسة X-Webhook-Delivery-Id. خزّنه وتجاوز ما عالجته سابقاً.

• ضع العمل الثقيل في طابور

  ادفع الحدث إلى طابور أو مهمة خلفية بدلاً من معالجته مباشرة.

• احرس السر

  خزّنه كما تخزن كلمة سر ودوّره من لوحة التحكم إذا تسرب يوماً.