Webhooks

تتيح لك Webhooks نسخ أحداث AskAIs Customer Service إلى أنظمتك الخاصة — أنظمة CRM والتحليلات و Slack وأي شيء يتحدث بروتوكول HTTP.

إنشاء webhook

انتقل إلى الإعدادات ← Webhooks ← Webhook جديد. اختر الأحداث، والصق عنوان URL الخاص بك، ثم احفظ. ستحصل على سر يُستخدم لتوقيع الحمولات.

أنواع الأحداث

• conversation.created
• conversation.updated — الحالة والأولوية والإسناد
• conversation.resolved
• message.created — أي رسالة، أي مُرسِل
• contact.created
• contact.updated

شكل الحمولة

POST https://your-app.com/webhooks/singlink
Content-Type: application/json
X-SingLink-Event: message.created
X-SingLink-Signature: sha256=ab12cd34...
X-SingLink-Timestamp: 1747300800

{
  "id": "evt_01HX...",
  "type": "message.created",
  "tenantId": "tnt_01HX...",
  "data": { /* event-specific payload */ }
}

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

احسب HMAC-SHA256 على timestamp + "." + rawBody باستخدام سر الـ webhook. قارنه بترويسة X-SingLink-Signature (بطريقة آمنة من حيث التوقيت).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-singlink-timestamp"];
  const sig = req.headers["x-singlink-signature"];
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

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

نعيد المحاولة على الاستجابات غير 2xx بتراجع أُسّي: 1s و 10s و 1m و 10m و 1h. بعد 5 محاولات يُوسَم الحدث على أنه فاشل؛ يمكنك رؤية حالات الفشل في لوحة الإدارة.

اختبار ping

يحتوي كل webhook على زر إرسال اختبار يرسل حدث webhook.ping وهميًا. مفيد للتحقق من أن نقطة النهاية لديك تقبل التوقيعات قبل الانتقال إلى الإنتاج.