Вебхуки (Webhooks)

Вебхуки позволяют получать события из Salebot в реальном времени на ваш сервер. В отличие от polling (периодических запросов), вебхуки отправляются мгновенно при наступлении события.

Архитектура: Salebot → HTTP POST → Ваш сервер (должен быть доступен по HTTPS).

Использование: Автоматизация, синхронизация данных, уведомления, интеграции.

Типы событий

💬 Сообщения

message.received — новое сообщение от клиента
message.sent — сообщение отправлено ботом
message.read — клиент прочитал сообщение

👤 Клиенты

client.created — создан новый клиент
client.updated — обновлены данные клиента
client.tagged — клиенту добавлен тег

🛒 Заказы

order.created — создан новый заказ
order.updated — изменён статус заказа
order.completed — заказ завершён

🤖 Боты

bot.started — бот активирован
bot.stopped — бот остановлен
bot.error — ошибка в работе бота

Настройка вебхуков

В личном кабинете Salebot перейдите в "Настройки" → "Интеграции" → "Вебхуки"
Нажмите "Добавить вебхук"
Заполните параметры:
- URL — адрес вашего сервера (обязательно HTTPS, кроме localhost)
- Секретный ключ — для подписи запросов (рекомендуется)
- Типы событий — выберите, какие события получать
- Активен — включить/выключить доставку
Сохраните настройки — Salebot отправит тестовое событие для проверки подключения
Ваш сервер должен вернуть HTTP 200 OK в течение 5 секунд
Если доставка не удалась, Salebot повторит попытку 3 раза с экспоненциальной задержкой

Формат запроса

Заголовки (Headers)

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Salebot-Event: message.received
X-Salebot-Signature: sha256=abc123...
X-Salebot-Delivery-ID: delivery_123456
User-Agent: Salebot-Webhooks/1.0

Тело (Body) — пример события message.received

{
  "event": "message.received",
  "data": {
    "message_id": "msg_789",
    "client_id": "client_456",
    "bot_id": "bot_123",
    "text": "Здравствуйте, хочу купить телефон",
    "channel": "telegram",
    "timestamp": "2025-01-20T14:30:45Z",
    "metadata": {
      "message_type": "text",
      "has_attachments": false
    }
  },
  "webhook_id": "wh_abc",
  "timestamp": "2025-01-20T14:30:46Z"
}

Проверка подписи (Signature Verification)

Для безопасности рекомендуется проверять подпись каждого запроса, чтобы убедиться, что он пришёл от Salebot.

Алгоритм проверки на Node.js

const crypto = require('crypto');

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

// Использование в Express
app.post('/webhook', (req, res) => {
    const signature = req.headers['x-salebot-signature'];
    const rawBody = JSON.stringify(req.body);
    
    if (!verifySignature(rawBody, signature, WEBHOOK_SECRET)) {
        return res.status(401).send('Invalid signature');
    }
    
    // Обработка события
    res.status(200).send('OK');
});

Практические примеры из опыта

Пример 1: Синхронизация чатов с внутренней системой тикетов

Задача: При первом сообщении от клиента создавать тикет в HelpDesk системе.

Решение: Настроили вебхук message.received, который фильтрует только первые сообщения (по отсутствию предыдущих в истории) и вызывает API HelpDesk.

# Python обработчик
def handle_webhook(data):
    event = data['event']
    if event == 'message.received':
        client_id = data['data']['client_id']
        # Проверяем, есть ли предыдущие сообщения
        if is_first_message(client_id):
            create_ticket(
                subject=f"Новый диалог от {client_id}",
                message=data['data']['text'],
                channel=data['data']['channel']
            )

Результат: Автоматическое создание тикетов, время ответа сократилось с 2 часов до 15 минут.

Пример 2: Real‑time дашборд для менеджеров

Задача: Выводить на большой экран в офисе количество новых сообщений в реальном времени.

Решение: Вебхук message.received отправляет событие в WebSocket сервер, который обновляет счётчик на всех подключённых клиентах.

// JavaScript (Node.js + Socket.io)
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

// Обработчик вебхука от Salebot
app.post('/webhook', (req, res) => {
    // Отправляем событие всем подключённым клиентам
    wss.clients.forEach(client => {
        if (client.readyState === WebSocket.OPEN) {
            client.send(JSON.stringify({
                type: 'new_message',
                data: req.body.data
            }));
        }
    });
    res.sendStatus(200);
});

Результат: Менеджеры видят активность в реальном времени, могут быстрее реагировать на пиковые нагрузки.

Отладка и мониторинг

Логи вебхуков — в личном кабинете Salebot есть история отправленных вебхуков с статусами доставки
Тестовые события — можно отправить тестовое событие вручную для проверки
Мониторинг uptime — рекомендуем использовать сервисы типа UptimeRobot для проверки доступности вашего webhook endpoint
Ретри (повторные попытки) — Salebot повторяет неудачные попытки 3 раза с интервалами 1, 5, 15 минут
Dead Letter Queue — после 3 неудачных попыток событие помещается в очередь просроченных, можно запросить вручную