API ReferenceВебхуки

Вебхуки

Не нужно опрашивать API в цикле. Передайте webhook_url при создании транскрипции — и мы сами отправим готовый результат к вам на сервер, как только он будет готов.

Коротко: передайте webhook_url в POST /v1/transcriptions — готовый payload придёт на этот URL. Выбирайте непредсказуемый путь: доставка не подписывается.

Регистрация вебхука

Отдельного ресурса подписки нет — вебхук привязывается к конкретной транскрипции через поле webhook_url при её создании. Укажите любой HTTPS-URL, который вы контролируете.

curl -X POST https://api.quillhub.ai/v1/transcriptions \
  -H "Authorization: Bearer $QAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtu.be/dQw4w9WgXcQ",
    "webhook_url": "https://your-app.example.com/hooks/quillai"
  }'

События

На одну транскрипцию приходит ровно одно событие — когда задача дошла до терминального состояния:

transcription.completed — транскрипция успешно завершена, поле result заполнено.
transcription.failed — транскрипция завершилась с ошибкой, причина лежит в error, баллы не списываются.

Тело запроса

В теле приходит полный объект Transcription — тот же формат, что возвращает GET /v1/transcriptions/{id}. Полную схему смотрите в API reference.

payload.jsonjson

{
  "id": "trs_01HZX9K7Q2M4YV8BTA6JRN3PDE",
  "status": "completed",
  "source": { "type": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ" },
  "duration_seconds": 842,
  "points_spent": 14,
  "result": {
    "text": "Welcome back to the channel. Today we're talking about...",
    "segments": [ /* ... */ ],
    "structured": { /* ... */ },
    "subtitles": {
      "vtt": "https://storage.quillhub.ai/subtitles/...vtt",
      "srt": "https://storage.quillhub.ai/subtitles/...srt"
    }
  },
  "webhook_url": "https://your-app.example.com/hooks/quillai",
  "error": null,
  "created_at": "2026-04-23T10:12:03Z",
  "completed_at": "2026-04-23T10:14:27Z"
}

Заголовки

X-QuillAI-Event — тип события: transcription.completed или transcription.failed.
X-QuillAI-Delivery — уникальный UUID конкретной попытки доставки. Используйте его для дедупликации, если повторная доставка придёт после успешной обработки первой.

Дополнительно мы отправляем Content-Type: application/json и User-Agent: QuillAI-Webhooks/1.0.

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

Доставка считается успешной, если ваш эндпоинт ответил 2xx в течение 10 секунд. Любой другой исход — не-2xx, таймаут, сетевая ошибка — запускает повторы по фиксированному расписанию: 1 минута, 5 минут, 30 минут, 2 часа, 12 часов. После 5 повторов (всего 6 попыток) доставка отменяется, и больше мы это событие не присылаем.

Локальное тестирование

Отдельного sandbox-эндпоинта для вебхуков пока нет. Чтобы тестировать против локального кода, прокиньте dev-сервер наружу через ngrok или smee.io и подставьте полученный публичный URL в webhook_url на тестовом ключе qai_test_.

← Назад

Аутентификация

Ошибки