إدارة الويبهوك

webhooks.list.subtitle

آخر تحديث: March 8, 2026

نظرة عامة

تسمح الويبهوكات لتجار Pause POS بتلقي إخطارات في الوقت الفعلي عند حدوث أحداث في نظام نقطة البيع الخاص بهم. يمكن للتجار تكوين نقاط نهاية HTTP مخصصة لتلقي حمولات JSON.

تم إكمال الطلب

عند مزامنة طلب نقاط البيع

تم استرجاع الطلب

عند استرجاع طلب أو إنشاء إشعار دائن

المخزون منخفض

عندما ينخفض مخزون المنتج عن الحد الأدنى

تم إغلاق الفترة

عند إغلاق فترة درج النقد

تكامل API

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

جميع دوال الويبهوك مُصدَّرة من `lib/api.ts` وجاهزة للاستخدام:

lib/api.ts - Webhook Functions
// 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

TypeScript Interfaces
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>;
}

مثال على حمل الويبهوك

هذا مثال على ما سيتلقاه نقطة نهاية الويبهوك الخاصة بك:

Example order.completed Event
{
  "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 ثانية
  • المهل الزمنية أو الأخطاء تشغل إعادة المحاولات التلقائية

منطق إعادة المحاولة التلقائية

يتم إعادة محاولة التسليمات الفاشلة تلقائياً وفقاً لهذا الجدول الزمني:

Retry Schedule
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 للاختبار والتصحيح المجاني:

  1. زيارة webhook.site
  2. انسخ عنوانك الفريد
  3. الصقه في تكوين الويبهوك الخاص بك
  4. قم بتشغيل حدث (على سبيل المثال، إكمال أمر)
  5. انظر إلى الطلب في الوقت الفعلي
Example Webhook Endpoint
// 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 لحماية بيانات العمل الحساسة في الانتقال.

هل تحتاج إلى مساعدة؟

فريق الدعم الخاص بنا هنا لمساعدتك في تكامل الويبهوكات.