API + Webhooks

Обзор

DBestChatBot отправляет исходящие вебхуки, когда в ваших чат-ботах происходят значимые события (захвачен лид, начался или завершился диалог, отправлено или получено сообщение). Вы указываете URL назначения в панели управления, и мы в течение нескольких секунд после каждого события отправляем на него POST-запрос с JSON-конвертом.

Вебхуки — функция тарифов Pro / Agency. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

События

Каждый webhook подписывается на один или несколько из этих типов событий:

Формат payload

Каждый вебхук отправляет 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 — уникальный ID доставки, используйте для дедупликации
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — подпись проверки

Проверка подписей (рекомендуется)

Всегда проверяйте полезные нагрузки вебхуков, чтобы убедиться, что они действительно пришли от DBestChatBot. Формат подписи совместим со Stripe: метка времени Unix t и hex-дайджест HMAC-SHA-256 v1, объединённые запятой.

Алгоритм:

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:

После 5-й неудачной попытки доставка помечается как failed и мы прекращаем повторные попытки. Полный журнал доставки (включая HTTP-статус, сообщение об ошибке и число попыток) доступен на странице вебхука в вашей панели управления.

Всегда быстро возвращать статус 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

Исходящие webhooks отправляются с наших production-серверов по адресу 15.204.199.41. Если вы используете белый список по IP, разрешите этот адрес. Однако подписи — более надёжный способ проверки: IP можно подделать, HMAC — нет (без секрета).

Начало работы

1. Перейти к Вебхуки в вашей панели управления
2. Нажмите Добавить endpoint — вставьте свой 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 → event Catch Hook → продолжить. Zapier покажет вам пользовательский URL вида https://hooks.zapier.com/hooks/catch/12345/abc/
2. В DBestChatBot перейдите в Вебхуки → Добавить endpoint. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, сохранить.
3. Вернитесь в Zapier: нажмите Тестовый триггерЗатем на странице вебхуков DBestChatBot нажмите Отправить тестовое событиеZapier должен получить тестовые данные — пример включает data.visitor.name, data.visitor.email, data.visitor.phone, и любые настроенные вами поля перед началом чата.
4. В Zapier добавьте Действие → HubSpot → event Создать или обновить контакт. Авторизуйте вашу учётную запись 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 → hardcode to Лид or Подписчик
   • HubSpot website ← Zapier data.source_url
6. Необязательно, но рекомендуется: добавьте второе действие → HubSpot → Create Note на этот контакт со ссылкой на расшифровку чата 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?

• Проверьте, что вебхук active в панели управления
• Check you're subscribed to the right event type
• Проверьте журнал доставки на странице вебхука на наличие ошибок HTTP
• Используйте Отправить тестовое событие button to bypass real-world triggers

Как временно приостановить получение событий?

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

Можно ли получить более ранние события, которые уже прошли?

Нет, вебхуки работают по принципу «отправил и забыл». Для исторических данных используйте панель управления Диалоги экспорт (CSV) или свяжитесь с нами насчёт разового переноса данных.