Укажите webhook_url вместе с записью
Параметр работает для видеоссылок, создания загрузки частями и как поле формы при отправке файла одним запросом. Совмещать его с reuse_recent нельзя. Формат запроса описан в настройке webhook_url.
Вебхуки удобны для фоновой обработки: интервью загрузили, исходный запрос закончился, а приложение продолжает ждать текст. Сохраните ID транскрибации рядом со своей задачей, чтобы потом сопоставить событие с действием пользователя.
Передайте конечный публичный HTTPS-адрес, без перенаправления. Его доступность проверяем и при создании задачи, и при доставке. localhost не подойдёт даже для разработки. Пример ниже использует файл, поэтому при проверке интеграции можно взять собственную запись.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Сохраните уведомление и быстро ответьте
В data приходит объект транскрибации без текста. Сочетание data.id и type помогает отсеять повторы. После transcription.completed прочитайте транскрипт через API.
Одно событие может прийти несколько раз. Например, обработчик успеет выполнить работу, но не ответит за 10 секунд. После проверки подписи надёжно сохраните событие или поставьте его в очередь и верните 2xx. Прежде чем публиковать материал или уведомлять пользователя, сохраните ключ из ID транскрибации и типа события, чтобы не выполнить действие дважды.
Сам текст загружайте по data.id в фоновой задаче. При transcription.failed прочитайте data.error и обновите статус в своём приложении. При отмене обратного вызова не будет: состояние нужно обновить там, где вы отменяете задачу.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Как проверить HMAC-подпись вебхука
Вычислите HMAC-SHA256 строки из t, точки и исходного тела запроса с секретом whsec_. Сравните подписи за постоянное время и отклоните устаревшую временную метку. Полный порядок действий — в руководстве по проверке подписи.
Прочитайте тело до JSON-парсера и используйте байты в том виде, в котором они пришли. Повторная сериализация может изменить пробелы или порядок ключей. Сначала проверьте заголовок и время, затем сравните подписи одинаковой длины, и только после успешной проверки разбирайте JSON.
Короткий пример ниже предполагает, что t и v1 уже извлечены и проверены. Полные примеры Node.js и Python в документации допускают расхождение времени до 5 минут. Используйте весь секрет вместе с префиксом whsec_. После его смены последующие доставки сразу подписываем новым ключом.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Проверьте повторы и ошибки до запуска
Пропустите через обработчик успешное событие, ошибку транскрибации и повтор уже обработанного события. Убедитесь, что материал не публикуется дважды, а ошибка не запускает публикацию без текста. Отдельно проверьте отклонение неверной подписи.
На ответ получателя отводится 10 секунд. Подтвердите получение, не дожидаясь индексации или ответа модели. Сохраните событие в своей очереди, а дальнейшие сбои обрабатывайте там. Повторы доставки от transcript1 не заменяют очередь вашего приложения.
При ошибке соединения, тайм-ауте или ответе вне 2xx повторяем доставку через 2, 4, 8, 16 и 32 минуты. Всего до 6 попыток. Перенаправления не отслеживаем. Записывайте в лог ID задачи, тип события и итог доставки, но никогда не секрет подписи.
Если попытки закончились, сверьте сохранённые ID через GET транскрибации. Храните ID с момента создания: отсутствие вебхука не должно быть единственной причиной отправлять запись заново.