إدارة الويبهوك
webhooks.list.subtitle
آخر تحديث: March 8, 2026
نظرة عامة
تسمح الويبهوكات لتجار Pause POS بتلقي إخطارات في الوقت الفعلي عند حدوث أحداث في نظام نقطة البيع الخاص بهم. يمكن للتجار تكوين نقاط نهاية HTTP مخصصة لتلقي حمولات JSON.
تم إكمال الطلب
عند مزامنة طلب نقاط البيع
تم استرجاع الطلب
عند استرجاع طلب أو إنشاء إشعار دائن
المخزون منخفض
عندما ينخفض مخزون المنتج عن الحد الأدنى
تم إغلاق الفترة
عند إغلاق فترة درج النقد
تكامل API
الدوال المتاحة
جميع دوال الويبهوك مُصدَّرة من `lib/api.ts` وجاهزة للاستخدام:
// Fetch all webhooks for current tenant
fetchWebhooks(): Promise<ApiWebhook[]>
// Get single webhook details
fetchWebhookById(id: number): Promise<ApiWebhook>
// Create new webhook (returns secret)
createWebhook(data: CreateWebhookInput): Promise<ApiWebhook & { secret: string }>
// Update webhook (events, headers, name)
updateWebhook(id: number, data: Partial<CreateWebhookInput>): Promise<ApiWebhook>
// Delete webhook
deleteWebhook(id: number): Promise<void>
// Rotate signing secret
rotateWebhookSecret(id: number): Promise<ApiWebhook & { secret: string }>
// Fetch delivery attempts log
fetchWebhookDeliveries(id: number, limit?: number): Promise<ApiWebhookDelivery[]>
// Manually retry a failed delivery
redeliverWebhook(webhookId: number, deliveryId: number): Promise<void>أنواع TypeScript
interface ApiWebhook {
id: number;
tenant_id: string;
name: string;
url: string;
events: string; // JSON array: ["order.completed","stock.low"]
secret?: string; // Only shown on creation
headers?: string; // Custom headers as JSON
is_active: boolean;
created_at: string;
updated_at: string;
}
interface ApiWebhookDelivery {
id: number;
tenant_id: string;
webhook_id: number;
event_type: string;
payload: string; // JSON payload sent
response_status: number; // HTTP status code
response_body: string; // Response from endpoint
attempt_count: number;
next_retry_at: string | null;
status: 'pending' | 'delivered' | 'failed' | 'retrying';
created_at: string;
updated_at: string;
}
interface CreateWebhookInput {
name: string;
url: string;
events: string[]; // Array of event types
headers?: Record<string, string>;
}مثال على حمل الويبهوك
هذا مثال على ما سيتلقاه نقطة نهاية الويبهوك الخاصة بك:
{
"id": "delivery-uuid",
"event": "order.completed",
"tenant_id": "tenant-uuid",
"created_at": "2026-03-08T10:30:00Z",
"data": {
"order_id": 123,
"invoice_number": "TAXINV-2026-000001",
"total_amount": 150.00,
"items_count": 3
}
}دليل التنفيذ
التعامل مع السر
يتم عرض سر الويبهوك مرة واحدة فقط بعد الإنشاء. يجب أن:
- احفظ السر بأمان على الخادم الخاص بك
- استخدمه للتحقق من توقيعات الويبهوك عبر HMAC-SHA256
- قم بتدوير السر بشكل دوري من أجل الأمان
- لا تفضح السر في كود جانب العميل
متطلبات عنوان URL للويبهوك
- يجب استخدام HTTPS (اتصال مشفر مطلوب)
- يجب أن تُرجع حالة HTTP 2xx لتأكيد التسليم
- يجب أن تستجيب خلال 30 ثانية
- المهل الزمنية أو الأخطاء تشغل إعادة المحاولات التلقائية
منطق إعادة المحاولة التلقائية
يتم إعادة محاولة التسليمات الفاشلة تلقائياً وفقاً لهذا الجدول الزمني:
Attempt 1: Immediate failure
Attempt 2: 1 minute later
Attempt 3: 5 minutes later
Attempt 4: 30 minutes later
Max attempts: 4 (then marked as failed)اختبار الويبهوكات الخاصة بك
مُوصى به: webhook.site
استخدم webhook.site للاختبار والتصحيح المجاني:
- زيارة webhook.site
- انسخ عنوانك الفريد
- الصقه في تكوين الويبهوك الخاص بك
- قم بتشغيل حدث (على سبيل المثال، إكمال أمر)
- انظر إلى الطلب في الوقت الفعلي
// Example webhook endpoint (Node.js)
import crypto from 'crypto';
app.post('/webhooks/pause', (req, res) => {
const signature = req.headers['x-pause-signature'];
const payload = JSON.stringify(req.body);
// Verify signature
const hash = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (hash !== signature) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process webhook
const { event, data } = req.body;
switch (event) {
case 'order.completed':
// Handle order completion
break;
case 'stock.low':
// Handle low stock alert
break;
}
// Return 200 OK to confirm delivery
res.json({ success: true });
});أفضل الممارسات
✅ تحقق دائماً من التوقيعات
تحقق من رأس X-Pause-Signature باستخدام HMAC-SHA256 للتأكد من أن الويبهوك جاء من Pause POS.
✅ الاستجابة بسرعة
يجب أن تستجيب نقطة نهاية الويبهوك الخاصة بك خلال 30 ثانية. ضع مهام طويلة الأجل في قائمة الانتظار بشكل متزامن.
✅ التعامل مع النسخ المكررة
قد يتم تسليم الويبهوكات عدة مرات. استخدم مفاتيح التوافقية (معرف الحدث) لمنع المعالجة المكررة.
✅ استخدم HTTPS فقط
يجب أن تستخدم جميع عناوين URL للويبهوك HTTPS لحماية بيانات العمل الحساسة في الانتقال.
هل تحتاج إلى مساعدة؟
فريق الدعم الخاص بنا هنا لمساعدتك في تكامل الويبهوكات.