ابدأ مجاناً
14 يوماً تجريبي مجاني - بدون بطاقة ائتمان
Hisab
الأسعار
المبيعات: 64 43 22 649 212+
ابدأ مجاناً

14 يوماً تجريبي مجاني - بدون بطاقة ائتمان

تسجيل الدخول
دليل Webhooks

وثائق Webhooks

استقبل إشعارات في الوقت الفعلي عندما تحدث أحداث في حسابك. قم ببناء تكاملات تفاعلية مع أحداث webhook.

نظرة عامة

تسمح Webhooks لتطبيقك باستقبال إشعارات HTTP في الوقت الفعلي عند حدوث أحداث في حسابك. بدلاً من الاستعلام المتكرر عن API للتغييرات، تقوم webhooks بإرسال البيانات إلى خادمك فور حدوثها.

كيف تعمل Webhooks

1
تسجيل نقطة نهاية Webhook

قم بتكوين عنوان URL في لوحة تحكم حساب حيث تريد استقبال أحداث webhook. يجب أن تستخدم نقطة النهاية HTTPS.

2
اختيار الأحداث للاشتراك

اختر الأحداث التي تريد استقبال إشعارات لها (مثل: invoice.finalized، customer.created).

3
استقبال ومعالجة الأحداث

عند حدوث حدث، يرسل حساب طلب HTTP POST إلى نقطة النهاية الخاصة بك مع بيانات الحدث. تحقق من التوقيع وقم بمعالجة الحدث.

اختبار Webhooks

استخدم خدمات مثل webhook.site أو ngrok لاختبار webhooks أثناء التطوير. يمكنك أيضًا استخدام ميزة اختبار webhook في لوحة تحكم حساب لإرسال أحداث تجريبية.

أنواع الأحداث

اشترك في الأحداث المهمة لتكاملك. كل حدث يمثل إجراءً محددًا حدث في حسابك.

Invoice Events

invoice.created

When a new invoice is created (draft status)

invoice.updated

When an invoice is modified

invoice.finalized

When an invoice is finalized and assigned an official number

invoice.sent

When an invoice is sent to the customer via email

invoice.paid

When an invoice is marked as paid

invoice.voided

When an invoice is voided/cancelled

Customer Events

customer.created

When a new customer is added

customer.updated

When customer information is modified

customer.deleted

When a customer is deleted

حمولات Webhook

جميع حمولات webhook تتبع هيكلاً موحدًا. يحتوي حقل data على المعلومات الخاصة بالحدث.

رؤوس HTTP

HTTP Headers
POST /webhooks/hisab HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-Hisab-Signature: a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0
X-Hisab-Timestamp: 1732713000000
X-Hisab-Event: invoice.finalized
X-Hisab-Delivery-ID: del_abc123
User-Agent: Hisab-Webhook/1.0

هيكل الحمولة

Example Payload
{
  "id": "evt_1234567890",
  "type": "invoice.finalized",
  "created": "2025-11-27T14:30:00Z",
  "data": {
    "id": "inv_abc123",
    "invoice_number": "INV-2025-00042",
    "status": "finalized",
    "customer_id": "cus_xyz789",
    "customer_name": "ACME Corporation",
    "currency": "MAD",
    "subtotal": "5000.00",
    "total_tax": "1000.00",
    "total": "6000.00",
    "issue_date": "2025-11-27",
    "due_date": "2025-12-27",
    "finalized_at": "2025-11-27T14:30:00Z",
    "items": [
      {
        "description": "Web Development Services",
        "quantity": "10",
        "unit_price": "500.00",
        "tax_rate": "20",
        "total": "6000.00"
      }
    ]
  },
  "organization_id": "org_123456"
}

حقول الحمولة

idstringمعرف فريد لهذا الحدث
typestringنوع الحدث (مثل: invoice.finalized)
createdstringطابع زمني ISO 8601 لوقت إنشاء الحدث
dataobjectبيانات الحدث التي تحتوي على الكائن ذي الصلة
organization_idstringمعرف مؤسستك

التحقق من التوقيع

يتضمن كل طلب webhook توقيعًا في رأس X-Hisab-Signature. تحقق دائمًا من هذا التوقيع للتأكد من أن webhook جاء من حساب ولم يتم التلاعب به.

تحذير أمني

لا تتخطى أبدًا التحقق من التوقيع في الإنتاج. بدونه، يمكن للجهات الخبيثة إرسال أحداث webhook مزيفة إلى نقطة النهاية الخاصة بك.

كيفية التحقق من التوقيعات

  1. استخرج رأسي X-Hisab-Signature و X-Hisab-Timestamp من الطلب
  2. اربط الطابع الزمني وجسم الطلب بنقطة: timestamp.body
  3. احسب تجزئة HMAC-SHA256 باستخدام سر webhook الخاص بك
  4. قارن التجزئة المحسوبة مع رأس التوقيع باستخدام مقارنة آمنة زمنيًا
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post('/webhooks/hisab', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hisab-signature'];
  const timestamp = req.headers['x-hisab-timestamp'];
  const payload = req.body.toString();

  // Verify timestamp is recent (within 5 minutes)
  const timestampAge = Date.now() - parseInt(timestamp);
  if (timestampAge > 300000) {
    return res.status(400).send('Timestamp too old');
  }

  // Verify signature
  const signedPayload = `${timestamp}.${payload}`;
  if (!verifyWebhookSignature(signedPayload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  // Handle the event
  switch (event.type) {
    case 'invoice.finalized':
      handleInvoiceFinalized(event.data);
      break;
    case 'invoice.paid':
      handleInvoicePaid(event.data);
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});

سياسة إعادة المحاولة

إذا لم تستجب نقطة النهاية برمز حالة 2xx، سيعيد حساب محاولة تسليم webhook باستخدام استراتيجية التراجع الأسي.

تسليم ناجح

أعد رمز حالة 2xx خلال 30 ثانية لتأكيد الاستلام

HTTP 2xx
تسليم فاشل

ردود 4xx و 5xx أو انتهاء المهلة ستؤدي إلى إعادة المحاولات التلقائية

HTTP 4xx, 5xx, timeout

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

المحاولة 1فورًا
المحاولة 2بعد 5 دقائق
المحاولة 3بعد 30 دقيقة
المحاولة 4بعد ساعتين
المحاولة 5بعد 24 ساعة

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

تحقق دائمًا من التوقيعات

تحقق من رأس X-Hisab-Signature في كل طلب لضمان الأصالة ومنع هجمات الانتحال.

استجب بسرعة

أعد استجابة 2xx خلال 30 ثانية. قم بمعالجة الحدث بشكل غير متزامن إذا لزم الأمر لتجنب انتهاء المهلة.

تعامل مع التكرار

خزن معرفات الأحداث المعالجة للتعامل بأناقة مع التسليمات المكررة. قد يتم تسليم نفس الحدث عدة مرات.

استخدم قوائم الانتظار في الخلفية

للمعالجة المعقدة، أكد استلام webhook فورًا وأضف الحدث إلى قائمة انتظار المهام في الخلفية.

أمّن نقطة النهاية

استخدم HTTPS فقط. اختياريًا أضف قائمة بيضاء لعناوين IP أو مصادقة إضافية لمزيد من الأمان.