Integration Guide

Webhook & API Integration Guide

Build custom integrations with HoverBot using event-driven webhooks and RESTful API endpoints for any platform or workflow.

Prerequisites

  • HoverBot workspace admin access with API key generated
  • HTTPS endpoint capable of receiving POST requests (for webhooks)
  • Familiarity with REST API patterns and JSON payloads

Authentication

All API requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.hoverbot.ai/v1/conversations

API keys are scoped to your workspace. Generate and rotate keys in Settings → API Keys.

Webhook Events

Configure webhooks in your workspace to receive real-time notifications for conversation events.

EventDescriptionUse Case
lead.qualifiedVisitor qualifies as a lead based on score thresholdCRM sync, sales notifications
conversation.escalatedConversation handed off to human agentHelpdesk ticket creation
conversation.completedConversation ended (resolved or abandoned)Analytics pipelines, CSAT triggers
conversation.feedbackUser submitted feedback or ratingQuality monitoring, alerting
guardrail.triggeredSafety or policy guardrail was activatedCompliance logging, incident review

Webhook Payload Structure

{
  "event": "lead.qualified",
  "timestamp": "2026-04-05T14:30:00Z",
  "workspaceId": "ws_abc123",
  "conversationId": "conv_xyz789",
  "data": {
    "email": "visitor@example.com",
    "qualificationScore": 82,
    "intent": "product_demo",
    "metadata": { ... },
    "conversationUrl": "https://app.hoverbot.ai/conversations/conv_xyz789"
  },
  "signature": "sha256=..."
}

Signature Verification

Every webhook includes an HMAC-SHA256 signature for payload verification:

import crypto from 'crypto';

function verifySignature(payload: string, signature: string, secret: string) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

REST API Endpoints

MethodEndpointDescription
GET/v1/conversationsList conversations with pagination and filters
GET/v1/conversations/:idGet conversation detail with messages
GET/v1/leadsList qualified leads with score and intent
GET/v1/analytics/summaryAggregated metrics for a date range
POST/v1/webhooksRegister a new webhook endpoint
POST/v1/knowledgeUpload or update knowledge base content

Full endpoint documentation, request/response schemas, and rate limits are in the API Reference.

Retry and Error Handling

  • Webhooks retry up to 3 times with exponential backoff (2s, 8s, 32s)
  • Your endpoint must return 2xx within 10 seconds to acknowledge receipt
  • Failed deliveries are logged in the webhook dashboard with payload and error details
  • API rate limits: 100 requests/minute per workspace (429 response with retry-after header)

Building a custom integration?

Full API ReferenceRequest Integration Support