Вебхуки

Сервис отправляет 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-подобном формате: полный текст, сегменты с таймкодами и спикерами, длительность.

[Контракт: webhookTranscriptionCompleted]

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

{
  "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-совместимом виде.

[Контракт: webhookTranscriptionFailed]

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

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

---

transcription.low.balance

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

[Контракт: webhookTranscriptionLowBalance]

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

{
  "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".

[Контракт: webhookTranscriptionLlmCompleted]

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

{
  "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": "gpt-oss-20b",
  "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 в течение нескольких секунд; при необходимости тяжёлую обработку лучше выполнять асинхронно после быстрого ответа.