Webhooks

Envelope

Every webhook POST body uses this envelope:

{
  "eventType": "lead.captured",        // one of the event types above
  "chatbotId": "a1b2c3d4-...",         // chatbot that triggered the event
  "chatbotName": "Support Bot",        // display name of the chatbot
  "organizationId": "e5f6g7h8-...",    // your organization ID
  "timestamp": "2026-10-15T10:30:00Z", // when the event occurred (ISO 8601 UTC)
  "deliveryId": "d9e0f1a2-...",        // unique ID for this delivery
  "data": { ... }                      // event-specific payload (below)
}

lead.captured

{
  "name": "Jane Smith",               // string | null
  "email": "jane@example.com",        // string | null
  "phone": "+1234567890",             // string | null
  "companyName": "Acme Inc",          // string | null
  "externalUserLoginId": "uuid-...",  // string | null — login record ID
  "externalUserId": "uuid-...",       // the lead; matches externalUserId on conversation events
  "tags": ["enterprise", "demo"],     // string[] | null — conversation tags
  "customFields": { "budget": "5k" }  // custom lead-form answers, keyed by field id
}

conversation.started

{
  "conversationId": "uuid-...",
  "externalUserId": "uuid-...",        // string | null
  "channel": "web",                    // "web", "whatsapp", "instagram" or "facebook"
  "senderExternalId": "15551234567",   // WhatsApp number or Instagram/Messenger ID; absent on web
  "metadata": { "page": "/pricing" }   // object | null — custom metadata from the chat session
}

conversation.message

{
  "conversationId": "uuid-...",
  "message": "How do I reset my password?",  // the visitor's message
  "externalUserId": "uuid-...",
  "channel": "web"
}

conversation.reply

{
  "conversationId": "uuid-...",
  "messageId": "uuid-...",                 // ID of the AI reply
  "userMessage": "How do I reset?",        // the visitor message it answers
  "reply": "To reset your password...",    // the full AI reply
  "externalUserId": "uuid-...",
  "channel": "web"
}

appointment.booked

{
  "conversationId": "uuid-...",
  "externalUserId": "uuid-...",
  "provider": "calcom",                    // the booking calendar's provider
  "calendarId": "...",                     // which calendar, when the chatbot has several
  "meetingType": "Intro call",
  "startUtc": "2026-10-20T15:00:00Z",
  "endUtc": "2026-10-20T15:30:00Z",
  "timeZone": "America/New_York",
  "bookingId": "...",
  "joinUrl": "https://...",
  "cancelUrl": "https://...",
  "attendeeName": "Jane Smith",
  "attendeeEmail": "jane@example.com"
}

Optional fields such as channel, senderExternalId, and the booking details are left out when they don't apply. Lead fields the visitor didn't give are sent as null.

Request Headers

Verifying Signatures

The X-Hyperleap-Signature header carries an HMAC-SHA256 signature of the raw request body, made with the signing secret. Verify it before trusting a request.

Node.js

const crypto = require('crypto');

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

Python

import hmac, hashlib

def verify_signature(payload: bytes, secret: str, signature_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)