API + Webhooks

Overview

DBestChatBot wysyła wychodzące webhooki, gdy w Twoich chatbotach zachodzą istotne zdarzenia (pozyskanie leada, rozpoczęcie lub zakończenie rozmowy, wysłanie lub odebranie wiadomości). Konfigurujesz docelowy URL w panelu, a my wysyłamy do niego kopertę JSON w ciągu kilku sekund od każdego zdarzenia.

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

Wydarzenia

Każdy webhook subskrybuje jeden lub więcej z tych typów zdarzeń:

Format payloadu

Każdy webhook wysyła kopertę JSON z tymi samymi polami najwyższego poziomu. data obiekt różni się w zależności od typu zdarzenia. Przykład dla 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"
  }
}

Nagłówki żądania

Każde żądanie zawiera:

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — nazwa zdarzenia
• X-DBestChatBot-Delivery: evt_abc123 — unikalny identyfikator dostawy, użyj do deduplikacji
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — podpis weryfikacyjny

Weryfikacja podpisów (zalecane)

Zawsze weryfikuj ładunki webhooków, aby upewnić się, że rzeczywiście pochodzą z DBestChatBot. Format podpisu jest zgodny ze Stripe: znacznik czasu Unix t oraz skrót hex HMAC-SHA-256 v1, oddzielone przecinkiem.

Algorytm:

1. Wyodrębnij t and v1 z nagłówka
2. Odrzuć, jeśli t różni się o więcej niż 5 minut od bieżącego czasu (ochrona przed powtórzeniem)
3. Oblicz expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. Porównanie w stałym czasie expected with v1
5. Jeśli są zgodne, ładunek jest autentyczny. W przeciwnym razie odrzuć.

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

Ponowne próby i gwarancje dostarczenia

Ponawiamy próby do 5 razy with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

Po 5. nieudanej próbie dostawa jest oznaczana jako failed i przestajemy ponawiać próby. Pełny dziennik dostarczeń (w tym status HTTP, komunikat błędu i liczbę prób) znajdziesz na stronie szczegółów webhooka w swoim panelu.

Zawsze szybko zwracaj status 2xx. Jeśli potrzebujesz wykonać ciężkie przetwarzanie, najpierw potwierdź kodem 200, a następnie przetwarzaj asynchronicznie.

Idempotencja

Każda dostawa ma unikalny id pole (wysyłane również jako 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.

Lista dozwolonych adresów IP

Wychodzące webhooki pochodzą z naszych serwerów produkcyjnych pod adresem 15.204.199.41. Jeśli używasz listy dozwolonych adresów IP, zezwól na ten adres. Podpisy są jednak bardziej niezawodną metodą weryfikacji — IP można podszyć się, HMAC nie (bez sekretu).

Pierwsze kroki

1. Przejdź do Webhooki w Twoim panelu
2. Kliknij Dodaj punkt końcowy — wklej swój URL, wybierz zdarzenia
3. Kopiuj signing secret wyświetlany po utworzeniu
4. Wyślij zdarzenie testowe, aby sprawdzić, czy Twój endpoint je odbiera i weryfikuje
5. Obserwuj na żywo, jak zdarzenia przepływają, gdy odwiedzający korzystają z Twoich chatbotów

Łączenie z 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 do Twojego CRM, Sheets lub gdziekolwiek dalej.

HubSpot — pełny przewodnik

To najczęstsza konfiguracja. Zapisuje każdego leada z chatbota jako kontakt w HubSpot:

1. W Zapier kliknij Utwórz Zap → Wyzwalacz: Webhooks by Zapier → zdarzenie Catch Hook → kontynuuj. Zapier pokaże Ci niestandardowy URL, np. https://hooks.zapier.com/hooks/catch/12345/abc/
2. W DBestChatBot przejdź do Webhooki → Dodaj punkt końcowy. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, zapisz.
3. Z powrotem w Zapier: kliknij Wyzwalacz testowyNastępnie na stronie webhooków DBestChatBot kliknij Wyślij zdarzenie testoweZapier powinien otrzymać przykładowy payload — przykład zawiera data.visitor.name, data.visitor.email, data.visitor.phone, oraz wszelkie zdefiniowane przez Ciebie niestandardowe pola przed czatem.
4. W Zapier dodaj Akcja → HubSpot → zdarzenie Utwórz lub zaktualizuj kontakt. Autoryzuj swoje konto HubSpot.
5. Zmapuj pola:
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (podziel na imię/nazwisko, jeśli potrzebujesz)
   • 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 → wpisz na stałe do Lead or Subskrybent
   • HubSpot website ← Zapier data.source_url
6. Opcjonalne, ale zalecane: dodaj drugą akcję → HubSpot → Utwórz notatkę na tym kontakcie z URL transkrypcji czatu data.transcript_url jako treść notatki. Twój zespół sprzedaży klika link i widzi całą rozmowę, która doprowadziła do pozyskania kontaktu.
7. Włącz Zap. Każde przyszłe lead.captured zdarzenie automatycznie tworzy / aktualizuje kontakt w HubSpot w ciągu kilku sekund.

Wskazówka: 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.

Inne systemy CRM: ten sam schemat działa dla Pipedrive (akcja: Create Deal), Salesforce (akcja: Create/Update Lead), Close (akcja: Create Lead), monday.com (akcja: Create Item) i Airtable (akcja: Create Record). Strona DBestChatBot jest identyczna — wystarczy skierować inny Zap na ten sam webhook URL.

FAQ

Why isn't my endpoint receiving events?

• Sprawdź, czy webhook jest active w panelu
• Check you're subscribed to the right event type
• Sprawdź dziennik dostarczania na stronie szczegółów webhooka pod kątem błędów HTTP
• Użyj Wyślij zdarzenie testowe button to bypass real-world triggers

Jak tymczasowo przestać otrzymywać zdarzenia?

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

Czy mogę pobrać starsze wydarzenia, które już się odbyły?

Nie, webhooki działają w trybie fire-and-forget. W przypadku danych historycznych skorzystaj z panelu Rozmowy eksport (CSV) lub skontaktuj się z nami w sprawie jednorazowego uzupełnienia danych.