All docs 참조

API + Webhooks

챗봇에서 이벤트가 발생하면 CRM, Slack, Zapier, n8n 또는 기타 시스템으로 실시간 HTTPS POST를 받습니다.

아웃바운드 웹훅

HMAC SHA-256 서명됨

백오프를 적용한 최대 5회 재시도

개요

DBestChatBot은 챗봇에서 의미 있는 이벤트가 발생할 때(리드 확보, 대화 시작 또는 종료, 메시지 발송 또는 수신) 아웃바운드 웹훅을 발생시킵니다. 대시보드에서 대상 URL을 설정하면 각 이벤트 발생 후 몇 초 안에 JSON 봉투를 해당 URL로 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은 다음 이벤트 유형 중 하나 이상을 구독합니다:

이벤트발동 시점
lead.captured방문자가 사전 채팅 양식을 제출하거나 WhatsApp 수신 메시지로 대화가 시작됨 (전화번호는 항상 확보). CRM 연동에 권장합니다.
conversation.started새 대화가 시작됩니다. 마케팅 분석이나 후속 워크플로를 즉시 시작하는 데 유용합니다.
conversation.ended방문자가 채팅을 닫거나 5분 이상 비활성 상태일 때입니다. 후속 이메일을 보내기에 좋습니다.
message.received방문자가 메시지를 보냈습니다. 대량 — 특정한 필요가 있을 때만 구독하세요.
message.sentAI가 방문자에게 답변했습니다. 대량 — 특정한 필요가 있을 때만 구독하세요.

페이로드 형식

모든 웹훅은 동일한 최상위 필드를 가진 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> — verification signature

서명 확인(권장)

웹훅 페이로드가 실제로 DBestChatBot에서 온 것인지 항상 확인하세요. 서명 형식은 Stripe 호환 방식입니다: Unix 타임스탬프 t 그리고 HMAC-SHA-256 16진수 다이제스트 v1, 쉼표로 구분됩니다.

알고리즘:

  1. 추출 t and v1 헤더에서
  2. 거부 조건 t 현재 시간으로부터 5분 이상 차이가 납니다 (재전송 방지)
  3. Compute 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:

시도이전 단계로부터 지연
1immediate
2+1분
3+5분
4+30분
5+2시간

5번째 시도가 실패하면 배송은 다음으로 표시됩니다. failed 재시도를 중단합니다. 대시보드의 웹훅 상세 페이지에서 전체 전송 로그(HTTP 상태, 오류 메시지, 시도 횟수 포함)를 확인할 수 있습니다.

항상 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 허용 목록

아웃바운드 웹훅은 다음 프로덕션 서버에서 발송됩니다 15.204.199.41. IP로 허용 목록을 설정하는 경우 이 주소를 허용하세요. 그러나 서명이 더 신뢰할 수 있는 검증 경로입니다 — IP는 스푸핑될 수 있지만 HMAC은 (비밀 없이는) 불가능합니다.

시작하기

  1. 이동 Webhooks 대시보드에서
  2. 클릭 엔드포인트 추가 — 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 Contact로 저장합니다:

  1. Zapier에서 클릭하세요: Zap 만들기 → 트리거: Webhooks by Zapier → 이벤트 Catch Hook → 계속하세요. 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, 저장하세요.
  3. Zapier로 돌아가서 클릭하세요: 테스트 트리거. 그런 다음 DBestChatBot 웹훅 페이지에서 클릭하세요 테스트 이벤트 보내기. Zapier가 샘플 페이로드를 받아야 합니다 — 샘플에는 다음이 포함됩니다 data.visitor.name, data.visitor.email, data.visitor.phone, 그리고 직접 정의한 모든 맞춤 사전 채팅 필드가 포함됩니다.
  4. Zapier에서 추가하세요: Action → 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. 선택 사항이지만 권장합니다: 두 번째 작업 추가 → 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 측은 동일합니다. 동일한 웹훅 URL에 다른 Zap을 연결하기만 하면 됩니다.

FAQ

Why isn't my endpoint receiving events?

  • 웹훅이 다음인지 확인하세요 active 대시보드에서
  • Check you're subscribed to the right event type
  • 웹훅 상세 페이지의 전송 로그에서 HTTP 오류를 확인하세요
  • 사용하세요 테스트 이벤트 보내기 button to bypass real-world triggers

이벤트 수신을 일시적으로 어떻게 중지하나요?

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

이미 지난 이벤트도 가져올 수 있나요?

아니요, 웹훅은 보내고 잊는 방식입니다. 과거 데이터는 대시보드를 이용하세요 대화 내보내기(CSV)하거나 일회성 백필에 대해 문의하세요.

연결할 준비가 되셨나요?

Open Webhooks 대시보드 열기