Вебхуки

Уведомления о событиях транскрипций, проверка подписи и ретраи

Вебхуки — это HTTPS-уведомления, которые наш сервис отправляет на ваш сервер, когда с асинхронной транскрипцией что-то происходит. Это удобнее опроса статуса: не нужно дёргать API, сервер сам сообщит о готовности.

Работают только для асинхронных транскрипций (async).

Настройка

Конфигурация вебхуков (URL, события, секрет) выполняется в вашем кабинете системой администрирования. Секрет (whsec_...) выдаётся один раз при создании вебхука — сохраните его: он нужен для проверки подписи.

События

Событие	Когда приходит	Дополнительные поля в теле
`transcription.created`	Задача создана	—
`transcription.ready`	Медиа готово к распознаванию	—
`transcription.processing`	Один раз, в начале распознавания	`progress_percent: 0`
`transcription.completed`	Распознавание завершено	`result` + `usage`
`transcription.failed`	Задача упала	`error`

transcription.completed и transcription.failed — обязательные события, их невозможно отключить при подписке.

Тело уведомления

Базовый конверт одинаков для всех событий:

{
  "event": "transcription.completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_type": "transcription",
  "status": "completed",
  "unix_timestamp": 1724300000,
  "result": {
    "text": "Добрый день, чем могу помочь?",
    "duration": 12.4
  },
  "usage": { "type": "duration", "seconds": 12 }
}

Для transcription.failed вместо result/usage приходит error:

{
  "event": "transcription.failed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_type": "transcription",
  "status": "failed",
  "unix_timestamp": 1724300000,
  "error": {
    "type": "insufficient_quota",
    "message": "Insufficient balance to process the transcription",
    "param": null,
    "code": "insufficient_balance"
  }
}

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

Каждый запрос содержит заголовок:

X-Webhook-Signature: hex(HMAC-SHA256(secret, rawBody))

Это HMAC‑SHA256 от сырого тела запроса (JSON байт-в-байт), подписанный вашим секретом whsec_....

Обязательно проверяйте подпись перед обработкой — так вы отсеете поддельные уведомления. Пример на Python:

import hmac, hashlib

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

Аналогично и на любом другом языке — везде есть HMAC‑SHA256.

Как подтвердить получение

Достаточно вернуть любой HTTP-статус меньше 400 в течение 120 секунд. Например, 200 OK с пустым телом. Если вы вернёте ошибку или не ответите — мы повторим доставку.

Ретраи

Параметр	Значение
Максимум попыток	5
Пауза между попытками	`номер попытки × 1 минута` (1, 2, 3, 4 мин...)
Таймаут ожидания ответа	120 секунд

unix_timestamp в теле не меняется при повторных доставках — его удобно использовать как защиту от дубликатов/устаревших событий.