Вебхуки

HTTP POST-уведомления о событиях транскрипции и LLM

Сервис отправляет HTTP POST-запросы (вебхуки) на URL, зарегистрированные пользователем, при наступлении событий: завершение транскрипции, ошибка, недостаток баланса, завершение LLM-запроса.

События

Событие	`X-Aiesa-Event`	Описание
Транскрипция успешно завершена	`transcription.completed`	Задача транскрипции выполнена, доступны результаты
Транскрипция завершилась с ошибкой	`transcription.failed`	Обработка не удалась (ошибка обработки, не низкий баланс)
Низкий баланс	`transcription.low.balance`	Недостаточно средств для выполнения транскрипции
LLM запрос выполнен	`transcription.llm.completed`	Завершён AI-анализ по транскрипции

Запрос

Метод: POST
В теле передаётся JSON с полями, зависящими от типа события (см. ниже).

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

Заголовок	Описание
`Content-Type`	`application/json`
`X-Aiesa-Signature`	Подпись: MD5 от секретного ключа вебхука. Секрет выдаётся в панели самообслуживания после создания вебхука. Рекомендуется проверять подпись на своей стороне.
`X-Aiesa-Event`	Тип события. Одно из значений: `transcription.completed`, `transcription.failed`, `transcription.llm.completed`, `transcription.low.balance`

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

Повторные попытки

При неуспешном ответе (не 2xx) сервис повторяет отправку с задержками (exponential backoff). Используется до 3 попыток; интервалы между попытками — 10 с, 30 с, 60 с.

`transcription.completed`

Транскрипция успешно завершена. Тело запроса в OpenAI-подобном формате: полный текст, сегменты с таймкодами и спикерами, длительность.

Контракт

Пример тела запроса:

{
  "transcription_id": "transcription-uuid",
  "task": "transcribe",
  "duration": 330.5,
  "text": "Полный текст транскрипции...",
  "segments": [
    {
      "type": "transcript.text.segment",
      "id": "seg_001",
      "start": 0.0,
      "end": 5.2,
      "text": "Фрагмент текста",
      "speaker": "unknown"
    }
  ],
  "usage": {
    "type": "duration",
    "seconds": 331
  }
}

`transcription.failed`

Транскрипция завершилась с ошибкой (не из-за низкого баланса). Тело в OpenAI-совместимом виде.

Контракт

Пример тела запроса:

{
  "transcription_id": "transcription-uuid",
  "task": "transcribe",
  "status": "failed",
  "error": {
    "type": "transcription_error",
    "message": "Описание ошибки",
    "code": "processing_failed"
  }
}

`transcription.low.balance`

Недостаточно баланса для выполнения транскрипции.

Контракт

Пример тела запроса:

{
  "object": "transcription.low.balance",
  "event": "transcription.low.balance",
  "id": "transcription-uuid",
  "transcription_id": "transcription-uuid",
  "user_id": "user-uuid",
  "created": 1234567890,
  "created_at": "2025-02-13T12:00:00+00:00",
  "occurred_at": "2025-02-13T12:00:05+00:00",
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance to process transcription",
    "type": "balance_error"
  }
}

`transcription.llm.completed`

Завершён LLM-запрос (AI-анализ). Формат совместим с идеей chat completion: есть choices[].message.content, при ошибке — error и finish_reason: "error".

Контракт

Пример тела запроса:

{
  "object": "transcription.llm.completed",
  "event": "transcription.llm.completed",
  "id": "transcription-uuid",
  "transcription_id": "transcription-uuid",
  "created": 1234567890,
  "created_at": "2025-02-13T12:00:00+00:00",
  "model": "aiesa-mini",
  "completed_at": "2025-02-13T12:01:00+00:00",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Текст ответа AI" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": null, "completion_tokens": null, "total_tokens": null },
  "prompt": "Сделай саммари встречи"
}

Регистрация URL и использование

Регистрация вебхуков и привязка к событиям выполняется в панели самообслуживания. После создания вебхука вы получаете секретный ключ — он используется для проверки заголовка X-Aiesa-Signature (MD5 от этого ключа). Сервис отправляет POST на указанный URL при наступлении выбранных событий.

Рекомендуется отвечать кодом 200 в течение нескольких секунд; при необходимости тяжёлую обработку лучше выполнять асинхронно после быстрого ответа.

Вебхуки

На этой странице