All docs 参考

API + Webhooks

当你的聊天机器人发生事件时，实时向你的 CRM、Slack、Zapier、n8n 或任何其他系统发送 HTTPS POST 请求。

出站 webhook

HMAC SHA-256 签名

最多重试 5 次，采用退避策略

概览

当你的聊天机器人发生重要事件时（捕获潜在客户、对话开始或结束、发送或接收消息），DBestChatBot 会触发出站 webhook。你在控制台中配置目标 URL，我们会在每个事件发生后几秒内向其 POST 一个 JSON 信封。

Webhooks 是 Pro / Agency 功能。 Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

Events

每个 webhook 订阅以下一种或多种事件类型：

Event触发时
lead.captured访客提交了聊天前表单，或一条 WhatsApp 入站消息开启了对话（我们总能拿到他们的手机号）。推荐用于 CRM 对接。
conversation.started新对话开始。适用于营销分析或立即启动后续工作流。
conversation.ended访客关闭聊天，或聊天超过 5 分钟无活动。适合触发跟进邮件。
message.received访客发送了一条消息。 高流量 — 仅在有特定需求时才订阅。
message.sentAI 已回复一位访客。 高流量 — 仅在有特定需求时才订阅。

负载格式

Every webhook POSTs a JSON envelope with the same top-level fields. The 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, 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:

尝试距上一条的延迟
1immediate
2+1 分钟
3+5 分钟
4+30 分钟
5+2 小时

第5次尝试失败后，配送状态将标记为 failed 随后我们停止重试。您可以在仪表盘的 webhook 详情页查看完整的投递日志（包括 HTTP 状态、错误消息和尝试次数）。

始终快速返回 2xx 状态码。如果您需要执行繁重处理，请先以 200 确认，然后异步处理。

幂等性

Every delivery has a unique 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. 点击 添加端点 — 粘贴你的 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 → continue. Zapier shows you a custom URL like https://hooks.zapier.com/hooks/catch/12345/abc/
  2. 在 DBestChatBot 中，前往 Webhooks → 添加端点. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured，保存。
  3. 回到 Zapier：点击 测试触发器. Then on your DBestChatBot webhook page, click 发送测试事件. Zapier should receive a sample payload — sample includes 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 (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 → hardcode to 线索 or 订阅者
    • HubSpot website ← Zapier data.source_url
  6. 可选但推荐： 添加第二个操作 → HubSpot → 创建备注 在该联系人上附带聊天记录 URL data.transcript_url 作为备注正文。你的销售团队点击链接即可看到促成此次捕获的完整对话。
  7. 开启Zap。此后每次 lead.captured event auto-creates / updates a HubSpot Contact within seconds.

专业提示： 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?

  • 检查 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.

我可以获取已经发生的较早事件吗？

不能，Webhook 是即发即忘的。如需历史数据，请使用仪表盘 对话 导出（CSV）或联系我们进行一次性回填。

准备好接入了吗？

打开 Webhooks 仪表盘