API + Webhooks

概要

DBestChatBotは、チャットボットで重要なイベント（リードの獲得、会話の開始や終了、メッセージの送受信）が発生すると、アウトバウンドWebhookを送信します。ダッシュボードで送信先URLを設定すると、各イベントから数秒以内にJSONエンベロープをPOSTします。

WebhooksはPro / Agencyの機能です。 Free-tier accounts can still view conversations and leads in the dashboard but can't pipe them to external systems.

イベント

各webhookは、次のイベントタイプの1つ以上を購読します：

ペイロード形式

すべてのWebhookは同じトップレベルフィールドを持つJSONエンベロープをPOSTします。 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> — 検証署名

署名の検証（推奨）

Webhookのペイロードが本当にDBestChatBotから来たものか常に検証してください。署名形式はStripe互換です：Unixタイムスタンプ t およびHMAC-SHA-256の16進ダイジェスト v1, joined with a comma.

アルゴリズム：

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ステータス、エラーメッセージ、試行回数を含む）は、ダッシュボードのWebhook詳細ページで確認できます。

常にすばやく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許可リスト

送信 Webhook は次の本番サーバーから発信されます 15.204.199.41。IP で許可リストを設定する場合は、このアドレスを許可してください。ただし、より信頼性の高い検証方法は署名です — IP は偽装できますが、HMAC は（シークレットなしでは）偽装できません。

はじめに

1. 移動する Webhooks ダッシュボードで
2. Click エンドポイントを追加 — URLを貼り付けて、イベントを選択
3. コピーする 署名シークレット 作成後に表示されます
4. テストイベントを送信して、エンドポイントが受信・検証できるか確認します
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のコンタクトとして取り込みます：

1. Zapierで、クリックします Zapを作成 → トリガー: Webhooks by Zapier → イベント キャッチフック → 続行。Zapierは次のようなカスタムURLを表示します https://hooks.zapier.com/hooks/catch/12345/abc/
2. DBestChatBotで、次に進みます Webhooks → エンドポイントを追加. Paste the Zapier URL, name it "HubSpot via Zapier," subscribe to lead.captured, save.
3. Zapierに戻って、クリックしてください テストトリガー次に、DBestChatBotのWebhookページで、次をクリックしてください： テストイベントを送信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. 任意ですが推奨: 2つ目のアクションを追加 → HubSpot → ノートを作成 その連絡先でチャット履歴のURL付き data.transcript_url をノート本文として。営業チームがリンクをクリックすると、キャプチャに至るまでの会話全体が表示されます。
7. Zapをオンにします。今後のすべての lead.captured イベントは数秒以内にHubSpotのコンタクトを自動で作成／更新します。

ヒント: 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（アクション：Create Deal）、Salesforce（アクション：Create/Update Lead）、Close（アクション：Create Lead）、monday.com（アクション：Create Item）、Airtable（アクション：Create Record）でも機能します。DBestChatBot側は同じで、同じwebhook URLに別のZapを向けるだけです。

FAQ

Why isn't my endpoint receiving events?

• webhookが次のとおりか確認してください active ダッシュボードで
• Check you're subscribed to the right event type
• webhookの詳細ページで配信ログを確認し、HTTPエラーがないかチェックしてください
• 次を使用 テストイベントを送信 button to bypass real-world triggers

イベントの受信を一時的に停止するにはどうすればいいですか？

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

すでに終了した過去のイベントも取得できますか？

いいえ、Webhookは送信しっぱなしです。過去のデータについてはダッシュボードをご利用ください 会話 エクスポート（CSV）するか、単発のバックフィルについてお問い合わせください。