API + Webhooks

ภาพรวม

DBestChatBot จะส่งเว็บฮุกขาออกเมื่อมีเหตุการณ์สำคัญเกิดขึ้นกับแชทบอทของคุณ (เก็บลีดได้ บทสนทนาเริ่มหรือสิ้นสุด มีการส่งหรือรับข้อความ) คุณกำหนด URL ปลายทางในแดชบอร์ด แล้วเราจะ POST ข้อมูล JSON ไปยัง URL นั้นภายในไม่กี่วินาทีหลังเกิดเหตุการณ์

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> — ลายเซ็นยืนยัน

การยืนยันลายเซ็น (แนะนำ)

ตรวจสอบเพย์โหลดเว็บฮุกเสมอเพื่อให้แน่ใจว่ามาจาก DBestChatBot จริง รูปแบบลายเซ็นเข้ากันได้กับ Stripe: Unix timestamp t และแฮช HMAC-SHA-256 แบบ hex 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 ที่อนุญาต

เว็บฮุกขาออกส่งต้นทางจากเซิร์ฟเวอร์โปรดักชันของเราที่ 15.204.199.41. หากคุณอนุญาตตาม IP ให้อนุญาตที่อยู่นี้ อย่างไรก็ตาม ลายเซ็นเป็นวิธีการตรวจสอบที่เชื่อถือได้มากกว่า — IP สามารถปลอมแปลงได้ แต่ HMAC ไม่สามารถ (หากไม่มีรหัสลับ)

เริ่มต้นใช้งาน

1. ไปที่ Webhooks ในแดชบอร์ดของคุณ
2. คลิก เพิ่ม endpoint — วาง URL ของคุณ เลือกอีเวนต์
3. คัดลอก signing secret แสดงหลังการสร้าง
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 Contact:

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 Contact โดยอัตโนมัติภายในไม่กี่วินาที

เคล็ดลับ: 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 (การกระทำ: สร้างดีล), Salesforce (การกระทำ: สร้าง/อัปเดตลีด), Close (การกระทำ: สร้างลีด), monday.com (การกระทำ: สร้างรายการ) และ Airtable (การกระทำ: สร้างเรกคอร์ด) ฝั่ง DBestChatBot เหมือนกันทุกประการ — เพียงชี้ Zap อื่นไปที่ URL ของ webhook เดียวกัน

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.

ฉันสามารถดึงอีเวนต์เก่าที่เกิดขึ้นแล้วได้หรือไม่?

ไม่ใช่ webhook เป็นแบบส่งแล้วจบ สำหรับข้อมูลย้อนหลัง ให้ใช้แดชบอร์ด การสนทนา ส่งออก (CSV) หรือติดต่อเราเกี่ยวกับการเติมข้อมูลย้อนหลังแบบครั้งเดียว