API + Webhooks

Tổng quan

DBestChatBot gửi webhook ra ngoài khi có sự kiện quan trọng xảy ra trên chatbot của bạn (thu thập được khách tiềm năng, cuộc trò chuyện bắt đầu hoặc kết thúc, tin nhắn được gửi hoặc nhận). Bạn cấu hình URL đích trong bảng điều khiển và chúng tôi POST một gói JSON đến đó trong vòng vài giây sau mỗi sự kiện.

Webhooks là tính năng của gói Pro / Agency. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

Sự kiện

Mỗi webhook đăng ký một hoặc nhiều loại sự kiện sau:

Định dạng payload

Mỗi webhook POST một gói JSON với các trường cấp cao nhất giống nhau. data đối tượng thay đổi theo loại sự kiện. Ví dụ cho 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"
  }
}

Tiêu đề yêu cầu

Mỗi yêu cầu bao gồm:

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — tên sự kiện
• X-DBestChatBot-Delivery: evt_abc123 — ID gửi duy nhất, dùng để loại trùng
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — chữ ký xác minh

Xác minh chữ ký (khuyến nghị)

Luôn xác minh payload webhook để đảm bảo chúng thực sự đến từ DBestChatBot. Định dạng chữ ký tương thích với Stripe: dấu thời gian Unix t và một chuỗi băm hex HMAC-SHA-256 v1, được nối bằng dấu phẩy.

Thuật toán:

1. Extract t and v1 từ phần đầu trang
2. Từ chối nếu t cách thời điểm hiện tại hơn 5 phút (bảo vệ chống phát lại)
3. Tính toán expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. So sánh thời gian hằng expected with v1
5. Nếu chúng khớp, dữ liệu tải là xác thực. Ngược lại, hãy từ chối.

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';

Thử lại và đảm bảo gửi

Chúng tôi thử lại tối đa 5 lần with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

Sau lần thử thất bại thứ 5, lần gửi được đánh dấu là failed và chúng tôi ngừng thử lại. Bạn có thể xem nhật ký gửi đầy đủ (bao gồm trạng thái HTTP, thông báo lỗi và số lần thử) trên trang chi tiết webhook trong bảng điều khiển của bạn.

Luôn trả về trạng thái 2xx nhanh chóng. Nếu bạn cần xử lý nặng, hãy xác nhận bằng 200 trước và xử lý bất đồng bộ.

Tính bất biến

Mỗi lần gửi có một id trường (cũng được gửi dưới dạng 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.

Danh sách IP được phép

Webhook gửi đi xuất phát từ máy chủ production của chúng tôi tại 15.204.199.41. Nếu bạn đưa vào danh sách cho phép theo IP, hãy cho phép địa chỉ này. Tuy nhiên, chữ ký là cách xác minh đáng tin cậy hơn — IP có thể bị giả mạo, HMAC thì không (nếu không có khóa bí mật).

Bắt đầu

1. Đi đến Webhooks trong bảng điều khiển của bạn
2. Nhấp Thêm endpoint — dán URL của bạn, chọn sự kiện
3. Sao chép signing secret hiển thị sau khi tạo
4. Gửi sự kiện thử nghiệm để xác minh endpoint của bạn nhận và xác thực sự kiện đó
5. Xem các sự kiện thực tế diễn ra khi khách truy cập sử dụng chatbot của bạn

Đang kết nối với 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 vào CRM, Sheets của bạn hoặc bất cứ đâu từ đó.

HubSpot — hướng dẫn đầy đủ

Đây là thiết lập phổ biến nhất. Ghi lại mọi khách hàng tiềm năng từ chatbot dưới dạng Liên hệ HubSpot:

1. Trong Zapier, nhấp Tạo Zap → Kích hoạt: Webhooks by Zapier → sự kiện Catch Hook → tiếp tục. Zapier sẽ hiển thị cho bạn một URL tùy chỉnh như https://hooks.zapier.com/hooks/catch/12345/abc/
2. Trong DBestChatBot, vào Webhooks → Thêm endpoint. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, lưu.
3. Quay lại Zapier: nhấp Test trigger. Sau đó trên trang webhook DBestChatBot của bạn, nhấp vào Gửi sự kiện thử nghiệm. Zapier sẽ nhận được một payload mẫu — mẫu bao gồm data.visitor.name, data.visitor.email, data.visitor.phone, và mọi trường trước trò chuyện tùy chỉnh mà bạn đã định nghĩa.
4. Trong Zapier, thêm một Action → HubSpot → sự kiện Tạo hoặc cập nhật liên hệ. Cấp quyền cho tài khoản HubSpot của bạn.
5. Ánh xạ các trường:
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (split first/last if you need)
   • 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 → gán cứng vào Lead or Người đăng ký
   • HubSpot website ← Zapier data.source_url
6. Tùy chọn nhưng được khuyến nghị: thêm hành động thứ hai → HubSpot → Tạo ghi chú trên liên hệ đó kèm URL bản ghi cuộc trò chuyện data.transcript_url làm nội dung ghi chú. Đội ngũ bán hàng của bạn nhấp vào liên kết và xem toàn bộ cuộc trò chuyện dẫn đến việc thu thập thông tin.
7. Bật Zap. Mọi lead.captured sự kiện tự động tạo / cập nhật một HubSpot Contact trong vài giây.

Pro tip: 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.

Các CRM khác: cùng một mô hình áp dụng cho Pipedrive (hành động: Create Deal), Salesforce (hành động: Create/Update Lead), Close (hành động: Create Lead), monday.com (hành động: Create Item) và Airtable (hành động: Create Record). Phía DBestChatBot là giống hệt nhau — chỉ cần trỏ một Zap khác vào cùng URL webhook.

FAQ

Why isn't my endpoint receiving events?

• Kiểm tra webhook đang active trong bảng điều khiển
• Check you're subscribed to the right event type
• Kiểm tra nhật ký gửi trên trang chi tiết webhook để tìm lỗi HTTP
• Dùng Gửi sự kiện thử nghiệm button to bypass real-world triggers

Làm sao để tạm ngừng nhận sự kiện?

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

Tôi có thể lấy các sự kiện cũ đã diễn ra không?

Không, webhook chỉ gửi một lần và không lưu lại. Để xem dữ liệu lịch sử, hãy dùng bảng điều khiển Hội thoại xuất (CSV) hoặc liên hệ với chúng tôi về việc bổ sung dữ liệu một lần.