Вебхуки¶

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

Создание подписки¶

1. Перейдите в раздел Webhooks в https://app.speaknode.com
2. Нажмите Create Webhook
3. Заполните параметры:

Типы событий¶

Выберите события, на которые вы хотите подписаться:

Вы можете подписаться на одно или несколько событий в рамках одной подписки.

Переключатель активности¶

Каждая подписка имеет переключатель Active / Inactive:

• Active — события отправляются на указанный URL
• Inactive — подписка приостановлена, события не отправляются

Это удобно для временного отключения вебхука без удаления подписки — например, на время технических работ.

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

При наступлении события платформа отправляет HTTP POST-запрос на указанный URL:

{
  "event": "ConversationComplete",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "session_id": "...",
    "agent_id": "...",
    "duration_seconds": 120,
    "status": "completed"
  }
}

Подпись запроса (HMAC-SHA256)¶

Для проверки подлинности запросов SpeakNode подписывает каждый вебхук с помощью HMAC-SHA256.

Секрет подписи¶

При создании подписки генерируется уникальный секретный ключ. Он отображается один раз — сохраните его в безопасном месте.

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

Каждый запрос содержит заголовок с подписью. Для проверки:

1. Извлеките тело запроса (raw body)
2. Вычислите HMAC-SHA256 от тела, используя ваш секретный ключ
3. Сравните вычисленное значение с подписью из заголовка

Пример проверки (Python):

import hmac
import hashlib

def verify_signature(body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

История запросов¶

Для каждой подписки доступна история отправленных запросов:

1. Откройте подписку в списке вебхуков
2. Перейдите на вкладку Request History
3. Просмотрите список запросов:
   • Время отправки — когда был отправлен запрос
   • Статус ответа — HTTP-код ответа вашего сервера
   • Тело запроса — полезная нагрузка, отправленная на ваш эндпоинт
   • Тело ответа — ответ вашего сервера

Рекомендации¶

• Отвечайте на вебхук кодом 200 как можно быстрее. Обработку данных выполняйте асинхронно
• Реализуйте идемпотентность — один и тот же запрос может быть доставлен повторно
• Храните секретный ключ в безопасном месте (переменные окружения, хранилище секретов)
• Логируйте входящие запросы для отладки