Webhooks

تُخطِر الـ webhooks خادمك عند وقوع أحداث المكالمات. تسجّل endpoint، وتُرسِل إليه Wave عبر POST بيانات JSON موقّعة، وتُعيد المحاولة عند الفشل.

تسجيل endpoint

تُدار الـ webhook endpoints في لوحة تحكّم Wave ضمن Webhooks: أضِف URL، واختر الأحداث، وانسخ الـ signing secret (يُعرَض مرّة واحدة).

الأحداث

يمكنك الاشتراك في أيّ حدث أدناه (بحدّ أقصى 5 endpoints لكلّ مشروع). اليوم، يُصدَر call.initiated فقط — أمّا البقيّة فمقبولة في قائمة السماح للاشتراك لكنّها لن تُطلَق حتّى يصل تدفّق الأحداث اللحظيّ.

الحدث	يُصدَر اليوم
`call.initiated`	✅ نعم
`call.answered` · `call.ended` · `call.missed` · `call.timeout` · `call.cancelled` · `call.failed`	قريبًا
`call.transferred` · `call.held` · `call.resumed`	مع الـ Calling SDK (لاحقًا)

الحمولة (Payload)

كلّ عمليّة تسليم هي جسم JSON يحتوي على نوع الـ event وكائن data. ويحمل الـ X-Wave-Event-Id header معرّفًا فريدًا لضمان عدم التكرار (idempotency).

{
  "event": "call.initiated",
  "data": {
    "call_id": "call_abc123",
    "status": "initiated",
    "direction": "outbound",
    "from": "+96651XXXXXXX",
    "customer_number_masked": "+96650••••17",
    "queue_id": null,
    "vitalpbx_channel_id": "…",
    "started_at": "2026-06-17T10:00:00.000Z",
    "metadata": {}
  }
}

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

كلّ عمليّة تسليم موقّعة. الـ X-Wave-Signature header هو sha256=<hex> — وهو HMAC-SHA256 لجسم الطلب الخام باستخدام الـ signing secret الخاصّ بالـ endpoint لديك (whsec_…). تحقّق منه عبر مقارنة بزمن ثابت (constant-time) قبل الوثوق بالحمولة:

import crypto from "node:crypto";

function verifyWaveSignature(rawBody, header, secret) {
  if (!header?.startsWith("sha256=")) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

احسب الـ HMAC على بايتات الجسم الخام، قبل أيّ تحليل/إعادة تسلسل لـ JSON — فإعادة التحويل إلى نصّ قد تُغيّر البايتات وتُفسِد التحقّق.

إعادة المحاولات والـ dead-letter

لكلّ محاولة مهلة قدرها 10 ثوانٍ. تُعاد عمليّات التسليم الفاشلة حتّى 5 محاولات وفق سلّم تراجع (backoff)، ثمّ تُحوَّل إلى dead-letter:

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

تُحوَّل عمليّات التسليم المُستنفَدة إلى dead-letter (تُحفَظ 72 ساعة) وتظهر — مع إجراء replay — في سجلّات التسليم بلوحة التحكّم.

البدء

Web Callback

المرجع

تسجيل endpoint

الأحداث

الحمولة (Payload)

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

إعادة المحاولات والـ dead-letter

​تسجيل endpoint

​الأحداث

​الحمولة (Payload)

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

​إعادة المحاولات والـ dead-letter

تسجيل endpoint

الأحداث

الحمولة (Payload)

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

إعادة المحاولات والـ dead-letter