API + Webhooks

نظرة عامة

يرسل DBestChatBot webhooks صادرة عند حدوث أحداث مهمة على روبوتات الدردشة لديك (التقاط عميل محتمل، بدء محادثة أو انتهاؤها، إرسال رسالة أو استلامها). تقوم بإعداد URL الوجهة في لوحة التحكم ونرسل حزمة JSON إليه خلال ثوانٍ من كل حدث.

Webhooks ميزة في Pro / Agency. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

الأحداث

يشترك كل webhook في نوع واحد أو أكثر من أنواع الأحداث هذه:

تنسيق الحمولة

كل webhook يرسل مغلف JSON بنفس الحقول العلوية. ال data يختلف الكائن حسب نوع الحدث. مثال على lead.captured:

{
  "event": "lead.captured",
  "id": "evt_abc123def456",
  "created_at": "2026-05-17T15:30:00+00:00",
  "data": {
    "conversation_id": "conv_xyz789",
    "chatbot": {
      "id": 42,
      "name": "Acme Support"
    },
    "visitor": {
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "phone": "+15551234567"
    },
    "source_url": "https://acme.com/pricing",
    "message_count": 4,
    "transcript_url": "https://dbestchatbot.com/app/conversations/conv_xyz789",
    "capture_method": "prechat_form"
  }
}

رؤوس الطلب

يتضمن كل طلب:

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — اسم الحدث
• X-DBestChatBot-Delivery: evt_abc123 — معرف تسليم فريد، يُستخدم لإزالة التكرار
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — توقيع التحقق

التحقق من التوقيعات (موصى به)

تحقق دائمًا من حمولات webhook للتأكد من أنها جاءت فعلًا من DBestChatBot. صيغة التوقيع متوافقة مع Stripe: طابع زمني Unix t وبصمة سداسية عشرية HMAC-SHA-256 v1, joined with a comma.

الخوارزمية:

1. استخراج t and v1 من الترويسة
2. ارفض إذا t يزيد عن 5 دقائق عن الوقت الحالي (حماية من إعادة التشغيل)
3. الحوسبة expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. مقارنة بزمن ثابت expected with v1
5. إذا تطابقت، فإن الحمولة أصلية. وإلا فارفضها.

Node.js / Express

// Node.js / Express example — verify the signature header
import express from 'express';
import crypto from 'crypto';

const app = express();
const SIGNING_SECRET = process.env.DBESTCHATBOT_SIGNING_SECRET;

// IMPORTANT: use raw body, not parsed JSON, for signature verification
app.post('/webhooks/dbestchatbot',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const header = req.header('X-DBestChatBot-Signature') || '';
    const match = header.match(/t=(\d+),v1=([a-f0-9]+)/);
    if (!match) return res.status(400).send('bad signature header');

    const [, ts, signature] = match;

    // 5-minute replay window
    if (Math.abs(Date.now() / 1000 - parseInt(ts)) > 300) {
      return res.status(400).send('stale timestamp');
    }

    const expected = crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(`${ts}.${req.body}`)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
      return res.status(401).send('signature mismatch');
    }

    const event = JSON.parse(req.body.toString());
    console.log('Verified event:', event.event, event.data);

    // Always respond 2xx quickly — we'll retry up to 5x with backoff if you don't
    res.status(200).send('ok');
  },
);

PHP

<?php
// PHP example — verify the signature header
$signingSecret = getenv('DBESTCHATBOT_SIGNING_SECRET');
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_DBESTCHATBOT_SIGNATURE'] ?? '';

if (! preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m)) {
    http_response_code(400); exit('bad signature header');
}
[, $ts, $signature] = $m;

if (abs(time() - (int) $ts) > 300) {
    http_response_code(400); exit('stale timestamp');
}

$expected = hash_hmac('sha256', "{$ts}.{$rawBody}", $signingSecret);
if (! hash_equals($expected, $signature)) {
    http_response_code(401); exit('signature mismatch');
}

$event = json_decode($rawBody, true);
// process $event['event'], $event['data'] ...

http_response_code(200);
echo 'ok';

إعادة المحاولات وضمانات التسليم

نعيد المحاولة حتى 5 مرات with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

بعد المحاولة الفاشلة الخامسة، تُعلَّم عملية التوصيل على أنها failed ونتوقف عن إعادة المحاولة. يمكنك الاطلاع على سجل التسليم الكامل (بما في ذلك حالة HTTP ورسالة الخطأ وعدد المحاولات) في صفحة تفاصيل الـ webhook في لوحة التحكم.

أعد دائمًا حالة 2xx بسرعة. If you need to do heavy processing, acknowledge with 200 first and process asynchronously.

اللاتكرارية

كل تسليم له فريد id الحقل (يُرسل أيضًا باسم X-DBestChatBot-Delivery). Because we retry on failure, your endpoint may receive the same event more than once. Store the IDs you've already processed and skip duplicates.

قائمة IP المسموح بها

تنشأ webhooks الصادرة من خوادم الإنتاج لدينا في 15.204.199.41. If you allowlist by IP, allow this address. Signatures are the more reliable verification path however — IP can spoof, HMAC cannot (without the secret).

البدء

1. انتقل إلى Webhooks في لوحة التحكم الخاصة بك
2. انقر أضف نقطة نهاية — الصق عنوان URL الخاص بك، واختر الأحداث
3. انسخ سر التوقيع يظهر بعد الإنشاء
4. أرسل حدثًا تجريبيًا للتحقق من أن نقطة النهاية لديك تستقبله وتتحقق منه
5. شاهد الأحداث الفعلية تتدفق أثناء استخدام الزوار لروبوتات الدردشة الخاصة بك

جارٍ الاتصال بـ Zapier / Make / n8n

All three tools have a generic "Catch Hook" or "Webhook Trigger" action — paste the URL they generate into a new endpoint here, subscribe to the events you want, done. Map fields from data.visitor إلى نظام CRM أو Sheets أو أي مكان آخر تختاره.

HubSpot — دليل كامل

هذا هو الإعداد الأكثر شيوعًا. يلتقط كل عميل محتمل من روبوت الدردشة كجهة اتصال في HubSpot:

1. في Zapier، انقر على إنشاء Zap → المشغّل: Webhooks by Zapier → الحدث Catch Hook → للمتابعة. يعرض لك Zapier رابطًا مخصصًا مثل https://hooks.zapier.com/hooks/catch/12345/abc/
2. في DBestChatBot، انتقل إلى Webhooks → أضف نقطة نهاية. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, save.
3. العودة إلى Zapier: انقر اختبار المشغّل. ثم في صفحة webhook الخاصة بـ DBestChatBot، اضغط على أرسل حدثًا تجريبيًا. يجب أن يستقبل Zapier حمولة نموذجية — يتضمن النموذج data.visitor.name, data.visitor.email, data.visitor.phone, وأي حقول مخصصة قبل الدردشة قمت بتعريفها.
4. في Zapier، أضف إجراء → HubSpot → الحدث إنشاء جهة اتصال أو تحديثها. Authorize your HubSpot account.
5. اربط الحقول:
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (قسّم الاسم الأول/الأخير إذا احتجت)
   • HubSpot phone ← Zapier data.visitor.phone
   • HubSpot company ← Zapier data.visitor.company (if you added a custom "Company" field in your chatbot's pre-chat form)
   • HubSpot lifecycle_stage → ثبّته مباشرةً في عميل محتمل or مشترك
   • HubSpot website ← Zapier data.source_url
6. اختياري لكنه موصى به: أضف إجراءً ثانيًا → HubSpot → إنشاء ملاحظة على جهة الاتصال تلك مع رابط نص المحادثة data.transcript_url كنص الملاحظة. ينقر فريق المبيعات على الرابط ويرى المحادثة الكاملة التي أدّت إلى الالتقاط.
7. فعّل الـ Zap. كل lead.captured يقوم الحدث بإنشاء / تحديث جهة اتصال HubSpot في غضون ثوانٍ.

نصيحة احترافية: if you want to route HIGH-VALUE leads differently (e.g. enterprise pricing inquiries) from FAQ-style chats, add a custom field to your pre-chat form like "What are you looking to do?" with options "Just browsing / Buying / Sales question." Then in Zapier add a Filter step that only continues to HubSpot if the answer is "Sales question" — your CRM stays clean.

أنظمة إدارة علاقات العملاء الأخرى: يعمل النمط نفسه مع Pipedrive (الإجراء: Create Deal)، وSalesforce (الإجراء: Create/Update Lead)، وClose (الإجراء: Create Lead)، وmonday.com (الإجراء: Create Item)، وAirtable (الإجراء: Create Record). جانب DBestChatBot متطابق — وجّه فقط Zap مختلفًا إلى عنوان webhook URL نفسه.

FAQ

Why isn't my endpoint receiving events?

• تحقق من أن webhook active في لوحة التحكم
• Check you're subscribed to the right event type
• تحقق من سجل التسليم في صفحة تفاصيل webhook بحثًا عن أخطاء HTTP
• استخدم أرسل حدثًا تجريبيًا button to bypass real-world triggers

كيف أتوقف عن تلقي الأحداث مؤقتًا؟

Toggle the webhook off — no events are queued or buffered, they're simply dropped.

هل يمكنني الحصول على الأحداث القديمة التي حدثت بالفعل؟

لا، الـ webhooks تُرسل دون انتظار رد. للبيانات التاريخية، استخدم لوحة التحكم المحادثات تصدير (CSV) أو تواصل معنا بخصوص تعبئة لمرة واحدة.