API + Webhooks

Genel bakış

DBestChatBot, sohbet botlarınızda anlamlı olaylar gerçekleştiğinde (potansiyel müşteri yakalanır, bir görüşme başlar veya biter, bir mesaj gönderilir veya alınır) giden webhook'lar tetikler. Kontrol panelinde bir hedef URL yapılandırırsınız ve her olaydan saniyeler içinde oraya bir JSON zarfı POST ederiz.

Webhook'lar bir Pro / Agency özelliğidir. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

Etkinlikler

Her webhook bu olay türlerinden birine veya birkaçına abone olur:

Yük formatı

Her webhook, aynı üst düzey alanlara sahip bir JSON zarfı POST eder. data nesne olay türüne göre değişir. Örnek: 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"
  }
}

İstek başlıkları

Her istek şunları içerir:

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — the event name
• X-DBestChatBot-Delivery: evt_abc123 — unique delivery ID, use for dedup
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — doğrulama imzası

İmzalar doğrulanıyor (önerilir)

Webhook yüklerinin gerçekten DBestChatBot'tan geldiğinden emin olmak için her zaman doğrulayın. İmza formatı Stripe ile uyumludur: bir Unix zaman damgası t ve bir HMAC-SHA-256 hex özeti v1, virgülle ayrılmış.

Algoritma:

1. Çıkar t and v1 başlıktan
2. Şu durumda reddet t geçerli saatten 5 dakikadan fazla ileride (tekrar saldırısı koruması)
3. Hesapla expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. Sabit zamanlı karşılaştırma expected with v1
5. Eşleşirlerse, yük özgündür. Aksi halde reddedin.

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

Yeniden denemeler ve teslimat garantileri

Şu kadar yeniden deniyoruz: 5 kez with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

5. başarısız denemeden sonra, teslimat şu şekilde işaretlenir: failed ve yeniden denemeyi durdururuz. Tam teslimat günlüğünü (HTTP durumu, hata mesajı ve deneme sayısı dahil) kontrol panelinizdeki webhook ayrıntı sayfasında görebilirsiniz.

Her zaman hızlıca 2xx durumu döndür. Ağır işlem yapmanız gerekiyorsa önce 200 ile onaylayın ve eşzamansız olarak işleyin.

Idempotency

Her teslimatın benzersiz bir id alan (ayrıca şu şekilde gönderilir: 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 izin listesi

Giden webhook'lar üretim sunucularımızdan şu adresten gönderilir: 15.204.199.41. IP ile izin listesi kullanıyorsanız bu adrese izin verin. Ancak imzalar daha güvenilir doğrulama yoludur — IP sahte olabilir, HMAC olamaz (gizli anahtar olmadan).

Başlarken

1. Şuraya git: Webhook'lar panonuzda
2. Tıkla Uç nokta ekle — paste your URL, pick events
3. Şunu kopyala imzalama gizli anahtarı oluşturulduktan sonra gösterilir
4. Uç noktanızın etkinliği alıp doğruladığını kontrol etmek için bir test etkinliği gönderin
5. Ziyaretçiler sohbet botlarınızı kullanırken gerçek olayların akışını izleyin

Zapier / Make / n8n'e bağlanılıyor

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'inize, Sheets'e veya oradan istediğiniz yere.

HubSpot — tam kılavuz

Bu en yaygın kurulumdur. Her sohbet botu ipucunu bir HubSpot Kişisi olarak yakalar:

1. Zapier'de şuna tıklayın Zap oluştur → Tetikleyici: Webhooks by Zapier → etkinlik Catch Hook → devam edin. Zapier size şuna benzer özel bir URL gösterir https://hooks.zapier.com/hooks/catch/12345/abc/
2. DBestChatBot'ta şuraya gidin Webhook'lar → Uç nokta ekle. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, kaydet.
3. Zapier'e dönün: tıklayın Test tetikleyici. Ardından DBestChatBot webhook sayfanızda şuna tıklayın Test etkinliği gönder. Zapier örnek bir yük almalı — örnek şunları içerir data.visitor.name, data.visitor.email, data.visitor.phone, ve tanımladığınız tüm özel sohbet öncesi alanlar.
4. Zapier'de bir şu ekleyin İşlem → HubSpot → etkinlik Kişi Oluştur veya Güncelle. HubSpot hesabınızı yetkilendirin.
5. Alanları eşleyin:
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (gerekirse ad/soyad olarak ayırın)
   • 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 → şuraya sabit kodlayın Potansiyel müşteri or Abone
   • HubSpot website ← Zapier data.source_url
6. İsteğe bağlı ancak önerilir: ikinci bir eylem ekle → HubSpot → Not Oluştur sohbet dökümü URL'si ile o kişiye data.transcript_url not gövdesi olarak. Satış ekibiniz bağlantıya tıklar ve bu kayda yol açan tüm görüşmeyi görür.
7. Zap'ı açın. Bundan sonraki her lead.captured etkinliği saniyeler içinde bir HubSpot Contact oluşturur / günceller.

İpucu: 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.

Diğer CRM'ler: aynı desen Pipedrive (action: Create Deal), Salesforce (action: Create/Update Lead), Close (action: Create Lead), monday.com (action: Create Item) ve Airtable (action: Create Record) için de işe yarar. DBestChatBot tarafı aynıdır — sadece farklı bir Zap'ı aynı webhook URL'sine yönlendirin.

FAQ

Why isn't my endpoint receiving events?

• Webhook'un şu olduğunu kontrol edin: active panoda
• Check you're subscribed to the right event type
• HTTP hataları için webhook ayrıntı sayfasındaki teslimat günlüğünü kontrol edin
• Şunu kullan Test etkinliği gönder button to bypass real-world triggers

Etkinlikleri geçici olarak almayı nasıl durdururum?

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

Daha önce gerçekleşmiş eski etkinlikleri alabilir miyim?

Hayır, webhook'lar gönder-ve-unut mantığıyla çalışır. Geçmiş veriler için panoyu kullanın Görüşmeler dışa aktarın (CSV) veya tek seferlik bir geriye dönük yükleme için bize ulaşın.