Вебхуки

Вебхуки дозволяють отримувати сповіщення в реальному часі, коли відбуваються події у вашому віджеті чату. Коли відвідувач починає чат, надсилає форму або повідомлення, 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. Використовуйте порівняння, безпечне щодо часу, для запобігання тайм-атакам