РуководстваPolling vs webhooks

Polling vs webhooks

Два способа узнать, что транскрипция готова. Polling — проще, webhooks — быстрее.

Коротко

В продакшене используйте webhooks. Polling отлично подходит для прототипов, разовых скриптов и CI-задач, где пара лишних секунд не важна.

Сравнение

Аспект	Polling	Webhooks
Задержка	3–5 сек (вы выбираете)	Обычно <1 сек после готовности
Инфраструктура	Нужен только HTTP-клиент	Публичный HTTPS-эндпоинт
Надёжность	Повторы на вашей стороне	До 5 повторов с backoff
Идемпотентность	Тривиально — повторный GET безопасен	Нужно дедуплицировать по X-QuillAI-Delivery
Лучше всего для	Прототипов, CLI, CI	Продакшен-приложений, реального времени

Polling

Создайте транскрипцию и делайте GET /v1/transcriptions/{id} с интервалом, пока статус не станет completed, failed или cancelled. Интервал выбираете вы — мы не ограничиваем разумный polling, но не злоупотребляйте.

poll.shbash

ID="trs_01HZX9K7Q2M4YV8BTA6JRN3PDE"
DELAY=3
while :; do
  RESP=$(curl -s https://api.quillhub.ai/v1/transcriptions/$ID \
    -H "Authorization: Bearer $QAI_KEY")
  STATUS=$(echo "$RESP" | jq -r .status)
  case "$STATUS" in
    completed|failed|cancelled) echo "$RESP" | jq .; break ;;
  esac
  sleep $DELAY
  DELAY=$(( DELAY < 10 ? DELAY + 2 : 10 ))
done

Совет: для долгих задач используйте jittered exponential backoff (3 сек → 5 сек → 10 сек). Не дёргайте API каждые 100 мс — вы только потратите round-trip.

Webhooks

Передайте webhook_url при создании транскрипции — как только она будет готова, мы отправим POST с объектом Transcription на этот URL. Про проверку подписи и повторы — в Webhooks.

create.shbash

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"
  }'

Когда что использовать

Polling подходит, когда…

Вы пишете скрипт, ноутбук или CI-задачу.
У вас нет публичного HTTPS-эндпоинта для колбэков.
Задержка не критична — пара секунд не проблема.

Webhooks подходят, когда…

У вас продакшен-приложение с требованиями к latency.
Вы не хотите блокировать воркер циклом опроса.
Вы обрабатываете задачи массово и polling умножит число запросов.

Гибридный подход

Страховка: основной путь — webhooks, а дополнительно — дешёвый reconciliation-поллер на всякий случай.

На практике webhook доставляется почти всегда, но сети бывают странными. После 5 неудачных повторов мы перестаём пытаться. Небольшой cron, который раз в час ищет задачи, застрявшие в processing более часа, и делает по ним GET — поймает все потерянные события без заметной нагрузки.

reconcile.tstypescript

// Runs hourly via cron. Picks up any job whose webhook was abandoned
// after 5 delivery attempts and reconciles it with the API.
const stale = await db.jobs.findMany({
  where: { status: "processing", createdAt: { lt: oneHourAgo() } },
});

for (const job of stale) {
  const res = await fetch(`https://api.quillhub.ai/v1/transcriptions/${job.id}`, {
    headers: { Authorization: `Bearer ${process.env.QAI_KEY}` },
  });
  const t = await res.json();
  if (["completed", "failed", "cancelled"].includes(t.status)) {
    await db.jobs.update({ where: { id: job.id }, data: { status: t.status, result: t } });
  }
}

Подводные камни

Слишком частый polling — интервалы меньше секунды не дают выигрыша и сжигают round-trip.
Нет дедупликации вебхуков — всегда проверяйте X-QuillAI-Delivery и пропускайте уже обработанные ID.
Эндпоинт без HTTPS. Мы не доставляем на http://-адреса.

← Назад

Транскрибация YouTube

Retry logic