إعداد خطاف ويب

سجّل نقطة وصول

سجّل عنوان خطاف ويب — ضمن الإعدادات/الخطافات في البوابة، أو عبر POST /portal/webhooks. يوصِّل الإصدار الأول حدث message.inbound. ويُرجَع السرّ التوقيعي مرة واحدة فقط عند التسجيل — احفظه؛ ستحتاجه للتحقّق من التسليمات.

حمولة message.inbound

عندما تستقبل Servus رسالة واردة، تُرسِل جسم JSON إلى كل عنوان مشترِك:

• { "event": "message.inbound", "tenantId", "conversationId", "contactId", "messageId", "channel": "WhatsApp", "fromAddress": "+15551230000", "body": "Hi there", "receivedAtUtc": "…" }
• ملاحظة: channel هنا اسم القناة نصّاً (مثل "WhatsApp")، وهو الموضع الوحيد الذي تُصدِر فيه الواجهة اسماً لا رقماً ترتيبياً.

تحقّق من التوقيع — دائماً

يحمل كل تسليم ترويسة X-Servus-Signature: HMAC-SHA256 على بايتات جسم الطلب الدقيقة، مفتاحها سرّك التوقيعي، بصيغة hex صغيرة. تحقّق منه قبل الوثوق بالحمولة، مقابل الجسم الخام (قبل تحليل JSON — فإعادة التسلسل قد تغيّر البايتات وتكسر التوقيع)، بمقارنة ثابتة الزمن.

• مع الحزمة: verifyWebhookSignature(rawBody, req.header(SERVUS_SIGNATURE_HEADER), secret).
• بدونها: createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')، ثم timingSafeEqual مقابل الترويسة.
• يجب رفض التوقيع الخاطئ/الناقص بـ 401 وتجاهل الحمولة.

إعادة المحاولة ودورة الحياة

تعيد الخطافات المحاولة بتراجع تدريجي عند الفشل، لذا ينبغي أن تكون نقطتك خاملة-التكرار (أزِل التكرار على messageId). يمكنك تعطيل/تفعيل اشتراك أو حذفه في أي وقت. راجع مثال verify-webhook.mjs القابل للتشغيل المرفق مع الحزمة.