استقبل إشعارات في الوقت الفعلي عندما تحدث أحداث في حسابك. قم ببناء تكاملات تفاعلية مع أحداث webhook.
تسمح Webhooks لتطبيقك باستقبال إشعارات HTTP في الوقت الفعلي عند حدوث أحداث في حسابك. بدلاً من الاستعلام المتكرر عن API للتغييرات، تقوم webhooks بإرسال البيانات إلى خادمك فور حدوثها.
قم بتكوين عنوان URL في لوحة تحكم حساب حيث تريد استقبال أحداث webhook. يجب أن تستخدم نقطة النهاية HTTPS.
اختر الأحداث التي تريد استقبال إشعارات لها (مثل: invoice.finalized، customer.created).
عند حدوث حدث، يرسل حساب طلب HTTP POST إلى نقطة النهاية الخاصة بك مع بيانات الحدث. تحقق من التوقيع وقم بمعالجة الحدث.
استخدم خدمات مثل webhook.site أو ngrok لاختبار webhooks أثناء التطوير. يمكنك أيضًا استخدام ميزة اختبار webhook في لوحة تحكم حساب لإرسال أحداث تجريبية.
اشترك في الأحداث المهمة لتكاملك. كل حدث يمثل إجراءً محددًا حدث في حسابك.
invoice.createdWhen a new invoice is created (draft status)
invoice.updatedWhen an invoice is modified
invoice.finalizedWhen an invoice is finalized and assigned an official number
invoice.sentWhen an invoice is sent to the customer via email
invoice.paidWhen an invoice is marked as paid
invoice.voidedWhen an invoice is voided/cancelled
customer.createdWhen a new customer is added
customer.updatedWhen customer information is modified
customer.deletedWhen a customer is deleted
جميع حمولات webhook تتبع هيكلاً موحدًا. يحتوي حقل data على المعلومات الخاصة بالحدث.
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{
"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 مزيفة إلى نقطة النهاية الخاصة بك.
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تحقق من رأس X-Hisab-Signature في كل طلب لضمان الأصالة ومنع هجمات الانتحال.
أعد استجابة 2xx خلال 30 ثانية. قم بمعالجة الحدث بشكل غير متزامن إذا لزم الأمر لتجنب انتهاء المهلة.
خزن معرفات الأحداث المعالجة للتعامل بأناقة مع التسليمات المكررة. قد يتم تسليم نفس الحدث عدة مرات.
للمعالجة المعقدة، أكد استلام webhook فورًا وأضف الحدث إلى قائمة انتظار المهام في الخلفية.
استخدم HTTPS فقط. اختياريًا أضف قائمة بيضاء لعناوين IP أو مصادقة إضافية لمزيد من الأمان.