API + Webhooks

Overview

DBestChatBot هنگام رخ دادن رویدادهای مهم در چت‌بات‌های شما (جذب سرنخ، شروع یا پایان گفتگو، ارسال یا دریافت پیام) وبهوک خروجی ارسال می‌کند. شما یک URL مقصد را در داشبورد تنظیم می‌کنید و ما ظرف چند ثانیه پس از هر رویداد، یک پاکت JSON به آن POST می‌کنیم.

Webhooks یک قابلیت Pro / Agency است. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

رویدادها

هر وبهوک به یک یا چند مورد از این انواع رویداد مشترک می‌شود:

قالب payload

هر 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 سازگار است: یک timestamp یونیکس t و یک هش hex با HMAC-SHA-256 v1، با کاما از هم جدا شده‌اند.

الگوریتم:

1. استخراج t and v1 از هدر
2. رد کنید اگر t بیش از ۵ دقیقه از زمان فعلی فاصله دارد (محافظت در برابر تکرار)
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';

تلاش‌های مجدد و تضمین تحویل

ما تا ۵ بار with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

پس از پنجمین تلاش ناموفق، ارسال به‌عنوان این وضعیت علامت‌گذاری می‌شود failed و تلاش مجدد را متوقف می‌کنیم. می‌توانید گزارش کامل تحویل (شامل وضعیت HTTP، پیام خطا و تعداد تلاش‌ها) را در صفحه جزئیات webhook در داشبورد خود ببینید.

همیشه به‌سرعت وضعیت 2xx برگردانید. اگر نیاز به پردازش سنگین دارید، ابتدا با 200 تأیید کنید و به‌صورت ناهمگام پردازش کنید.

تکرارپذیری

هر تحویل یک 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

وب‌هوک‌های خروجی از سرورهای تولید ما در این آدرس ارسال می‌شوند 15.204.199.41. اگر با IP فهرست مجاز می‌سازید، این آدرس را مجاز کنید. با این حال، امضاها مسیر تأیید قابل‌اعتمادتری هستند — IP قابل جعل است، HMAC نه (بدون کلید مخفی).

شروع کار

1. برو به Webhooks در داشبورد شما
2. کلیک کنید افزودن endpoint — URL خود را جای‌گذاری کنید، رویدادها را انتخاب کنید
3. کپی کنید کلید امضای محرمانه پس از ایجاد نمایش داده می‌شود
4. یک رویداد آزمایشی بفرستید تا مطمئن شوید endpoint شما آن را دریافت و اعتبارسنجی می‌کند
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 یک URL سفارشی مانند این به شما نشان می‌دهد https://hooks.zapier.com/hooks/catch/12345/abc/
2. در DBestChatBot، به بخش Webhooks → افزودن endpoint. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured، ذخیره کنید.
3. بازگشت به Zapier: کلیک کنید تست تریگرسپس در صفحه webhook مربوط به DBestChatBot خود، کلیک کنید ارسال رویداد آزمایشیZapier باید یک payload نمونه دریافت کند — نمونه شامل data.visitor.name, data.visitor.email, data.visitor.phone، و هر فیلد سفارشی پیش از چت که تعریف کرده‌اید.
4. در Zapier، یک اقدام → HubSpot → رویداد ساخت یا به‌روزرسانی مخاطب. حساب HubSpot خود را مجاز کنید.
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 → ایجاد یادداشت روی آن مخاطب همراه با URL متن چت 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.

سایر CRMها: همین الگو برای Pipedrive (اکشن: Create Deal)، Salesforce (اکشن: Create/Update Lead)، Close (اکشن: Create Lead)، monday.com (اکشن: Create Item) و Airtable (اکشن: Create Record) هم کار می‌کند. سمت DBestChatBot یکسان است — فقط یک Zap متفاوت را به همان URL وبهوک متصل کنید.

FAQ

Why isn't my endpoint receiving events?

• بررسی کنید که webhook active در داشبورد
• Check you're subscribed to the right event type
• برای خطاهای HTTP، گزارش تحویل را در صفحه جزئیات webhook بررسی کنید
• از ارسال رویداد آزمایشی button to bypass real-world triggers

چگونه به‌طور موقت دریافت رویدادها را متوقف کنم؟

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

آیا می‌توانم رویدادهای قدیمی‌تری را که قبلاً برگزار شده‌اند دریافت کنم؟

خیر، وب‌هوک‌ها به‌صورت ارسال و فراموشی عمل می‌کنند. برای داده‌های تاریخی از داشبورد استفاده کنید گفتگوها خروجی (CSV) بگیرید یا دربارهٔ یک بار پرکردن مجدد با ما تماس بگیرید.