API + Webhooks

Ringkasan

DBestChatBot mengirim webhook keluar saat peristiwa penting terjadi pada chatbot Anda (prospek ditangkap, percakapan dimulai atau berakhir, pesan dikirim atau diterima). Anda mengonfigurasi URL tujuan di dasbor dan kami mengirim POST amplop JSON ke sana dalam hitungan detik setelah setiap peristiwa.

Webhook adalah fitur Pro / Agency. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

Acara

Setiap webhook berlangganan satu atau lebih jenis peristiwa berikut:

Format payload

Setiap webhook mengirim POST amplop JSON dengan field tingkat atas yang sama. data objek bervariasi menurut jenis peristiwa. Contoh untuk 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"
  }
}

Header permintaan

Setiap permintaan mencakup:

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — nama event
• X-DBestChatBot-Delivery: evt_abc123 — ID pengiriman unik, gunakan untuk deduplikasi
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — tanda tangan verifikasi

Memverifikasi tanda tangan (disarankan)

Selalu verifikasi payload webhook untuk memastikan benar-benar berasal dari DBestChatBot. Format tanda tangan kompatibel dengan Stripe: timestamp Unix t dan digest hex HMAC-SHA-256 v1, joined with a comma.

Algoritma:

1. Ekstrak t and v1 dari header
2. Tolak jika t lebih dari 5 menit dari waktu saat ini (perlindungan replay)
3. Komputasi expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. Perbandingan waktu konstan expected with v1
5. Jika cocok, payload tersebut autentik. Jika tidak, tolak.

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

Percobaan ulang dan jaminan pengiriman

Kami mencoba ulang hingga 5 kali with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

Setelah percobaan gagal ke-5, pengiriman ditandai sebagai failed dan kami berhenti mencoba ulang. Anda dapat melihat log pengiriman lengkap (termasuk status HTTP, pesan error, dan jumlah percobaan) di halaman detail webhook pada dashboard Anda.

Selalu kembalikan status 2xx dengan cepat. Jika Anda perlu melakukan pemrosesan berat, akui dengan 200 terlebih dahulu dan proses secara asinkron.

Idempotensi

Setiap pengiriman memiliki id field (juga dikirim sebagai 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.

Daftar IP yang diizinkan

Webhook keluar berasal dari server produksi kami di 15.204.199.41. Jika Anda menggunakan allowlist berdasarkan IP, izinkan alamat ini. Namun tanda tangan adalah jalur verifikasi yang lebih andal — IP dapat dipalsukan, HMAC tidak (tanpa rahasianya).

Memulai

1. Buka Webhook di dasbor Anda
2. Klik Tambah endpoint — tempel URL Anda, pilih event
3. Salin signing secret ditampilkan setelah dibuat
4. Kirim event uji coba untuk memverifikasi endpoint Anda menerima dan memvalidasinya
5. Saksikan event nyata mengalir saat pengunjung menggunakan chatbot Anda

Menghubungkan ke 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 ke CRM, Sheets, atau ke mana pun dari sana.

HubSpot — panduan lengkap

Ini adalah pengaturan yang paling umum. Menangkap setiap lead chatbot sebagai Kontak HubSpot:

1. Di Zapier, klik Buat Zap → Pemicu: Webhooks by Zapier → event Catch Hook → lanjutkan. Zapier menunjukkan URL khusus seperti https://hooks.zapier.com/hooks/catch/12345/abc/
2. Di DBestChatBot, buka Webhook → Tambah endpoint. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, simpan.
3. Kembali di Zapier: klik Pemicu ujiLalu di halaman webhook DBestChatBot Anda, klik Kirim event uji cobaZapier seharusnya menerima contoh payload — contohnya mencakup data.visitor.name, data.visitor.email, data.visitor.phone, dan bidang pra-obrolan kustom apa pun yang Anda tentukan.
4. Di Zapier, tambahkan Tindakan → HubSpot → event Buat atau Perbarui Kontak. Otorisasi akun HubSpot Anda.
5. Petakan kolomnya:
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (pisahkan nama depan/belakang jika perlu)
   • 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 Lead or Pelanggan
   • HubSpot website ← Zapier data.source_url
6. Opsional tetapi disarankan: tambahkan tindakan kedua → HubSpot → Create Note pada kontak itu dengan URL transkrip chat data.transcript_url sebagai isi catatan. Tim penjualan Anda mengklik tautan dan melihat percakapan lengkap yang menghasilkan capture.
7. Aktifkan Zap. Setiap lead.captured acara otomatis membuat / memperbarui Kontak HubSpot dalam hitungan detik.

Tips Pro: 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 lainnya: pola yang sama berlaku untuk Pipedrive (action: Create Deal), Salesforce (action: Create/Update Lead), Close (action: Create Lead), monday.com (action: Create Item), dan Airtable (action: Create Record). Sisi DBestChatBot identik — cukup arahkan Zap yang berbeda ke URL webhook yang sama.

FAQ

Why isn't my endpoint receiving events?

• Periksa apakah webhook active di dasbor
• Check you're subscribed to the right event type
• Periksa log pengiriman di halaman detail webhook untuk kesalahan HTTP
• Gunakan Kirim event uji coba button to bypass real-world triggers

Bagaimana cara menghentikan penerimaan acara untuk sementara?

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

Bisakah saya mendapatkan acara lama yang sudah terjadi?

Tidak, webhook bersifat fire-and-forget. Untuk data historis, gunakan dasbor Percakapan ekspor (CSV) atau hubungi kami untuk backfill sekali jalan.