Вебхуки

Вебхуки позволяют получать уведомления в реальном времени, когда происходят события в вашем виджете чата. Когда посетитель начинает чат, отправляет форму или сообщение, Chatim отправляет HTTP POST запрос на ваш URL с данными события.

Обзор

С вебхуками вы можете:

• Автоматически отправлять новых лидов в вашу CRM
• Запускать рабочие процессы в Zapier, Make или пользовательских приложениях
• Записывать события чата в вашу аналитическую платформу
• Уведомлять вашу команду в Slack или других инструментах
• Синхронизировать данные посетителей с вашей базой данных

Доступ к вебхукам

1. Войдите в свою панель управления Chatim
2. Выберите свой проект на боковой панели
3. Нажмите Webhooks в меню навигации

Создание вебхука

1. Нажмите Создать вебхук
2. Введите необязательное Название (напр., "Интеграция CRM")
3. Введите URL, куда должны отправляться события
4. Выберите одно или несколько Событий, которые хотите получать
5. Нажмите Создать

После создания вы увидите Секрет вебхука - скопируйте и сохраните его немедленно. Этот секрет используется для проверки того, что входящие запросы поступают от Chatim. Он показывается только один раз.

Поддерживаемые события

Полезная нагрузка вебхука

Каждая доставка вебхука - это HTTP POST запрос с JSON телом.

Общие поля

{
  "event": "chat.started",
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "projectUuid": "your-project-uuid",
  "chatUuid": "visitor-chat-uuid",
  "data": { }
}

chat.started

Включает информацию о посетителе, URL страницы, местоположение и агент пользователя.

{
  "event": "chat.started",
  "data": {
    "visitor": {
      "uuid": "visitor-uuid",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "page": {
      "url": "https://example.com/pricing",
      "title": "Pricing - Example"
    },
    "location": { "country": "US", "city": "Los Angeles" },
    "userAgent": { "browser": "Chrome", "os": "Windows", "device": "Desktop" }
  }
}

chat.message.received

{
  "event": "chat.message.received",
  "data": {
    "messageUuid": "message-uuid",
    "message": "Hi, I have a question about your pricing.",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.form.submitted

{
  "event": "chat.form.submitted",
  "data": {
    "formNodeId": "node-id",
    "formName": "Contact Form",
    "fields": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "message": "I'd like a product demo."
    },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.closed

Включает кто закрыл чат (agent, visitor, system или timeout), длительность в секундах, количество сообщений и транскрипт.

{
  "event": "chat.closed",
  "data": {
    "closedBy": "agent",
    "status": "closed",
    "duration": 345,
    "messageCount": 12,
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.assigned

Отправляется, когда агент поддержки присоединяется к разговору.

{
  "event": "chat.assigned",
  "data": {
    "assignedTo": { "uuid": "agent-uuid", "name": "Jane Smith" },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.handoff

Отправляется, когда чат-бот переходит в режим живого чата.

{
  "event": "chat.handoff",
  "data": {
    "reason": "Visitor requested human support",
    "fromNode": "node-id",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

Безопасность

Проверка подписи

Каждый запрос вебхука содержит подпись, чтобы вы могли проверить, что он пришёл от Chatim. Подпись вычисляется как HMAC-SHA256(secret, timestamp + "." + payload) и отправляется в заголовке X-Chatim-Signature.

Заголовки запроса

Пример проверки Node.js

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-chatim-signature'];
  const timestamp = req.headers['x-chatim-timestamp'];
  const body = JSON.stringify(req.body);

  // Reject requests older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Пример проверки Python

import hmac, hashlib, time

def verify_webhook(headers, body, secret):
    signature = headers.get('X-Chatim-Signature', '')
    timestamp = headers.get('X-Chatim-Timestamp', '')

    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        f'{timestamp}.{body}'.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Логика повторных попыток

Если ваш эндпоинт недоступен или возвращает ошибку, Chatim автоматически повторяет попытку.

После 5 неудачных попыток доставка помечается как неудачная. Ответы 2xx считаются успехом, 4xx - постоянными ошибками (без повтора), 5xx и тайм-ауты (30с) запускают повторные попытки.

Если вебхук накапливает 10 последовательных неудач, он автоматически отключается. Вы можете повторно включить его из панели управления после исправления проблемы.

Управление вебхуками

Тестирование

Нажмите Тест на любом вебхуке, чтобы отправить пример события chat.started на ваш URL. Это позволяет проверить ваш эндпоинт перед запуском.

История доставок

Нажмите на вебхук, чтобы просмотреть недавние доставки с типом события, меткой времени, кодом состояния HTTP и сообщениями об ошибках. История хранится 30 дней.

Перегенерация секрета

Если секрет вебхука скомпрометирован, нажмите Перегенерировать секрет, сохраните новый секрет и обновите ваш эндпоинт. Старый секрет немедленно становится недействительным.

Сценарии использования

Интеграция с CRM

Подпишитесь на chat.form.submitted и chat.started, чтобы автоматически создавать контакты и лидов в вашей CRM.

Уведомления Slack

Подпишитесь на chat.assigned и chat.handoff, чтобы оповещать вашу команду, когда посетитель нуждается в живой поддержке.

Аналитика

Подпишитесь на все события, чтобы построить полную картину вовлечённости в чате, показателей конверсии форм и времени ответа поддержки.

Автоматизация электронной почты

Подпишитесь на chat.form.submitted, чтобы запускать приветственные письма, последовательности последующих действий или сообщения подтверждения.

Лучшие практики

• Возвращайте ответ 2xx быстро - обрабатывайте данные асинхронно
• Используйте HTTPS для URL вашего эндпоинта
• Всегда проверяйте подпись вебхука перед обработкой
• Реализуйте идемпотентность, используя eventId для обработки дублирующих доставок
• Храните секрет вебхука безопасно (переменная окружения, менеджер секретов)
• Валидируйте метку времени для предотвращения атак воспроизведения (отклоняйте запросы старше 5 минут)

Устранение неполадок

Вебхук не получает события

1. Проверьте, что вебхук Активен (не отключён)
2. Проверьте правильность URL и его публичную доступность
3. Используйте кнопку Тест для отправки примера события
4. Проверьте журналы сервера на входящие запросы
5. Убедитесь, что ваш эндпоинт возвращает код состояния 2xx

Вебхук автоматически отключён

1. Проверьте причину отключения в панели управления
2. Исправьте основную проблему (эндпоинт недоступен, возвращает ошибки)
3. Нажмите Включить для реактивации
4. Используйте Тест для проверки перед повторным включением

Проверка подписи не проходит

1. Убедитесь, что используете правильный секрет
2. Проверьте, что подписываете timestamp + "." + raw_body (не распарсенный JSON)
3. Используйте сравнение, безопасное по времени, для предотвращения тайминг-атак