API + Webhooks

Огляд

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.

Події

Кожен webhook підписується на один або кілька з цих типів подій:

Формат payload

Кожен webhook надсилає POST із 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> — підпис перевірки

Перевірка підписів (рекомендовано)

Завжди перевіряйте дані webhook, щоб переконатися, що вони справді надійшли від DBestChatBot. Формат підпису сумісний зі Stripe: Unix-мітка часу t та шістнадцятковий дайджест 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, повідомленням про помилку та кількістю спроб) можна переглянути на сторінці деталей 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-адреси

Вихідні webhook надходять із наших робочих серверів за адресою 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: натисніть Тестовий тригерПотім на сторінці вебхуків DBestChatBot натисніть Надіслати тестову подіюZapier має отримати зразок даних — зразок містить 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 на той самий webhook 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) або зв’яжіться з нами щодо разового заповнення.