Webhooks

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

تسجيل endpoint

تُدار الـ webhook endpoints في لوحة تحكّم Wave ضمن Webhooks: أضِف URL، واختر الأحداث، وانسخ الـ signing secret (يُعرَض مرّة واحدة). يجب أن يكون الـ URL رابط https عامًّا. ترفض Wave أيّ URL يشير إلى عنوان loopback أو خاصّ أو link-local أو أيّ عنوان داخلي آخر (400 WEBHOOK_URL_INVALID). تتحقّق Wave من العنوان مرّة أخرى قبل كلّ إرسال، ولا تتبع عمليات إعادة التوجيه.

بيئة واحدة لكلّ endpoint

ينتمي كلّ endpoint إلى بيئة واحدة: sandbox أو production. ويستقبل أحداث بيئته فقط، فلا تصل أحداث الاختبار أبدًا إلى الـ endpoint الحيّ. في مشروع الـ production، تعرض لوحة التحكّم الـ endpoints الخاصّة بعرض البيئة المحدّد، ويأخذ الـ endpoint الجديد بيئة ذلك العرض.

يمكنك إضافة الـ URL نفسه مرّة واحدة في كلّ بيئة؛ ولكلّ نسخة signing secret خاصّ بها.
الحدّ الأقصى 5 endpoints يُحتسب لكلّ بيئة.
لا يستطيع مشروع الـ sandbox إضافة endpoint للـ production. أضِفه في نموذج Go-Live بدلًا من ذلك: يبقى غير نشط حتّى توافق Wave على طلبك، ويعرض النموذج الـ signing secret الخاصّ به مرّة واحدة. إذا رفضت Wave الطلب، يُحذف الـ endpoint.

الأحداث

يمكنك الاشتراك في أيّ حدث أدناه (بحدّ أقصى 5 endpoints لكلّ مشروع).

الحدث	delivery
`call.initiated`	`direct`
`call.answered`	`event_stream`
`call.ended`	`event_stream`
`call.missed`	`event_stream`
`call.timeout`	`event_stream` (انتظرت المكالمة في طابور المحرّك أكثر من الحدّ الأقصى، 10 دقائق، وأُزيلت قبل الاتصال)؛ وفي الـ sandbox `direct` (الرقم `+966500000016`)
`call.cancelled`	`direct` لإلغاء callback؛ و`event_stream` لإنهاء مكالمة ما زالت في طابور المحرّك (لا يتمّ الاتصال بها)
`call.failed`	`event_stream`
`call.transferred`	`event_stream`
`call.held`	`not_sent_yet`
`call.resumed`	`not_sent_yet`
`call.input`	`direct`
`voice_auth.completed`	`direct`
`verify.completed`	`direct`
`voicemail.received`	`direct`
`message.received`	`event_stream`
`message.delivered`	`event_stream`
`message.read`	`event_stream`
`message.failed`	`event_stream`
`conference.created`	`event_stream`
`conference.member_joined`	`event_stream`
`conference.member_left`	`event_stream`
`conference.ended`	`event_stream`
`campaign.recipient_completed`	`event_stream`
`campaign.completed`	`event_stream`

الحمولة (Payload)

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

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

يقع environment بجانب event وخارج data. وقيمته "sandbox" أو "production". تأخذه Wave من المكالمة: المكالمة التي أجراها sandbox key قيمتها "sandbox"، والمكالمات الواردة "production". أمّا webhook النتيجة voice_auth.completed فيأخذه من مفتاح الـ challenge. ويحمل كلّ حدث بيئة مكالمته، بما في ذلك أحداث Verify والـ callback والبريد الصوتي والمؤتمر والـ IVR والتحويل.

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

كلّ عمليّة تسليم موقّعة. الـ 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 ساعة) وتظهر في سجلّات التسليم بلوحة التحكّم، بعلامة مُحوَّل إلى Dead-letter.

البدء

الصوت

Web Callback

واتساب

المرجع

تسجيل endpoint

بيئة واحدة لكلّ endpoint

الأحداث

الحمولة (Payload)

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

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

​تسجيل endpoint

​بيئة واحدة لكلّ endpoint

​الأحداث

​الحمولة (Payload)

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

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

تسجيل endpoint

بيئة واحدة لكلّ endpoint

الأحداث

الحمولة (Payload)

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

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