تُخطِر الـ 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 | بعد ساعتين |
