API + Webhooks

Aperçu

DBestChatBot envoie des webhooks sortants lorsque des événements importants se produisent sur vos chatbots (un prospect est capturé, une conversation commence ou se termine, un message est envoyé ou reçu). Vous configurez une URL de destination dans le tableau de bord et nous y envoyons une enveloppe JSON en POST dans les secondes suivant chaque événement.

Les webhooks sont une fonctionnalité Pro / Agency. Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

Événements

Chaque webhook s'abonne à un ou plusieurs de ces types d'événements :

Format du payload

Chaque webhook envoie une enveloppe JSON avec les mêmes champs de premier niveau. Le data l'objet varie selon le type d'événement. Exemple pour 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"
  }
}

En-têtes de requête

Chaque requête inclut :

• Content-Type: application/json
• User-Agent: DBestChatBot-Webhook/1.0
• X-DBestChatBot-Event: lead.captured — le nom de l'événement
• X-DBestChatBot-Delivery: evt_abc123 — ID de livraison unique, à utiliser pour la déduplication
• X-DBestChatBot-Signature: t=1747490400,v1=<hex_hmac> — signature de vérification

Vérification des signatures (recommandé)

Vérifiez toujours les payloads de webhook pour vous assurer qu'ils proviennent bien de DBestChatBot. Le format de signature est compatible Stripe : un horodatage Unix t et un condensé hexadécimal HMAC-SHA-256 v1, joints par une virgule.

Algorithme :

1. Extraire t and v1 depuis l'en-tête
2. Rejeter si t date de plus de 5 minutes par rapport à l'heure actuelle (protection contre la relecture)
3. Calculer expected = HMAC_SHA256(signing_secret, "t.raw_request_body")
4. Comparaison à temps constant expected with v1
5. S'ils correspondent, la charge utile est authentique. Sinon, rejetez-la.

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

Nouvelles tentatives et garanties de livraison

Nous réessayons jusqu'à 5 fois with exponential backoff if your endpoint doesn't return a 2xx response within 30 seconds:

Après la 5e tentative échouée, la livraison est marquée comme failed et nous arrêtons les tentatives. Vous pouvez consulter le journal complet des livraisons (statut HTTP, message d'erreur et nombre de tentatives inclus) sur la page de détail du webhook dans votre tableau de bord.

Toujours renvoyer rapidement un statut 2xx. Si vous devez effectuer un traitement lourd, accusez réception avec un 200 d'abord et traitez de façon asynchrone.

Idempotence

Chaque livraison dispose d'un id champ (également envoyé comme 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.

Liste blanche IP

Les webhooks sortants proviennent de nos serveurs de production à 15.204.199.41. Si vous autorisez par IP, autorisez cette adresse. Les signatures restent toutefois la méthode de vérification la plus fiable — une IP peut être usurpée, pas un HMAC (sans le secret).

Pour commencer

1. Aller à Webhooks dans votre tableau de bord
2. Cliquez Ajouter un endpoint — collez votre URL, choisissez les événements
3. Copiez le secret de signature affiché après la création
4. Envoyez un événement de test pour vérifier que votre endpoint le reçoit et le valide
5. Regardez les événements réels défiler à mesure que les visiteurs utilisent vos chatbots

Connexion à 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 vers votre CRM, Sheets ou ailleurs à partir de là.

HubSpot — guide complet

C'est la configuration la plus courante. Chaque lead du chatbot est enregistré comme Contact HubSpot :

1. Dans Zapier, cliquez sur Créer un Zap → Déclencheur : Webhooks by Zapier → event Accroche → continuer. Zapier vous affiche une URL personnalisée du type https://hooks.zapier.com/hooks/catch/12345/abc/
2. Dans DBestChatBot, allez dans Webhooks → Ajouter un endpoint. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, enregistrer.
3. De retour dans Zapier : cliquez sur Déclencheur de testEnsuite, sur votre page de webhook DBestChatBot, cliquez sur Envoyer l'événement de testZapier devrait recevoir une charge utile d'exemple — l'exemple inclut data.visitor.name, data.visitor.email, data.visitor.phone, et tous les champs personnalisés avant chat que vous avez définis.
4. Dans Zapier, ajoutez un Action → HubSpot → event Créer ou mettre à jour un contact. Autorisez votre compte HubSpot.
5. Associez les champs :
   • HubSpot email ← Zapier data.visitor.email
   • HubSpot firstname ← Zapier data.visitor.name (séparez prénom/nom si besoin)
   • 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 Abonné
   • HubSpot website ← Zapier data.source_url
6. Facultatif mais recommandé : ajouter une seconde action → HubSpot → Créer une note sur ce contact avec l'URL de la transcription du chat data.transcript_url comme corps de la note. Votre équipe commerciale clique sur le lien et voit toute la conversation qui a mené à la capture.
7. Activez le Zap. Chaque futur lead.captured l'événement crée / met à jour automatiquement un Contact HubSpot en quelques secondes.

Astuce : 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.

Autres CRM : le même schéma fonctionne pour Pipedrive (action : Create Deal), Salesforce (action : Create/Update Lead), Close (action : Create Lead), monday.com (action : Create Item) et Airtable (action : Create Record). Côté DBestChatBot, c'est identique — il suffit de pointer un autre Zap vers la même URL de webhook.

FAQ

Why isn't my endpoint receiving events?

• Vérifiez que le webhook est active dans le tableau de bord
• Check you're subscribed to the right event type
• Consultez le journal de livraison sur la page de détail du webhook pour les erreurs HTTP
• Utilisez le Envoyer l'événement de test button to bypass real-world triggers

Comment suspendre temporairement la réception des événements ?

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

Puis-je récupérer des événements plus anciens déjà passés ?

Non, les webhooks sont en mode fire-and-forget. Pour les données historiques, utilisez le tableau de bord Conversations export (CSV) ou contactez-nous pour un remplissage ponctuel.