# Вебхук транскрибации с проверкой подписи

> Получайте вебхук, когда транскрибация завершится или выдаст ошибку. Укажите webhook_url: transcript1 отправит подписанный POST вместо опроса статуса.

Canonical: https://transcript1.com/ru/features/vebhuk-transkribatsiya
Language: ru
Last updated: 2026-10-19

Вебхук транскрибации избавляет ваше приложение от постоянного опроса статуса. При создании задачи передайте webhook_url. Когда обработка завершится или выдаст ошибку, отправим на этот адрес подписанный POST.

- События transcription.completed и transcription.failed
- Подпись HMAC-SHA256 при каждой доставке
- До 6 попыток с увеличением интервала

## Получите событие и прочитайте готовый транскрипт

### Готовность или ошибка

Отправляем transcription.completed и transcription.failed. При отмене транскрибации вебхук не приходит.

### Подпись каждого запроса

В X-Transcript1-Signature передаём временную метку и HMAC-SHA256 исходного тела запроса. Для подписи используем секрет команды с префиксом whsec_.

### Повторяем доставку при сбое

Ответ 2xx подтверждает доставку. В остальных случаях повторяем через 2, 4, 8, 16 и 32 минуты. Всего делаем до 6 попыток.

### Только публичный HTTPS-адрес

Проверяем адрес при создании задачи и перед каждой доставкой. Он должен использовать HTTPS и указывать на публичный адрес.

### Событие без длинного текста

В уведомлении приходит объект транскрибации без самого транскрипта. Получите текст отдельно по ID в нужном формате.

## Укажите webhook\_url вместе с записью

Параметр работает для видеоссылок, создания загрузки частями и как поле формы при отправке файла одним запросом. Совмещать его с reuse_recent нельзя. Формат запроса описан в [настройке webhook_url](https://transcript1.com/ru/docs/webhooks#set-a-webhook-url).

Вебхуки удобны для фоновой обработки: интервью загрузили, исходный запрос закончился, а приложение продолжает ждать текст. Сохраните ID транскрибации рядом со своей задачей, чтобы потом сопоставить событие с действием пользователя.

Передайте конечный публичный HTTPS-адрес, без перенаправления. Его доступность проверяем и при создании задачи, и при доставке. localhost не подойдёт даже для разработки. Пример ниже использует файл, поэтому при проверке интеграции можно взять собственную запись.

### Загрузка файла с вебхуком

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Сохраните уведомление и быстро ответьте

В data приходит объект транскрибации без текста. Сочетание data.id и type помогает отсеять повторы. После transcription.completed [прочитайте транскрипт через API](https://transcript1.com/ru/docs/api-reference#get-a-transcription).

Одно событие может прийти несколько раз. Например, обработчик успеет выполнить работу, но не ответит за 10 секунд. После проверки подписи надёжно сохраните событие или поставьте его в очередь и верните 2xx. Прежде чем публиковать материал или уведомлять пользователя, сохраните ключ из ID транскрибации и типа события, чтобы не выполнить действие дважды.

Сам текст загружайте по data.id в фоновой задаче. При transcription.failed прочитайте data.error и обновите статус в своём приложении. При отмене обратного вызова не будет: состояние нужно обновить там, где вы отменяете задачу.

### POST на ваш адрес

```
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_. Сравните подписи за постоянное время и отклоните устаревшую временную метку. Полный порядок действий — в [руководстве по проверке подписи](https://transcript1.com/ru/docs/webhooks#verify-the-signature).

Прочитайте тело до JSON-парсера и используйте байты в том виде, в котором они пришли. Повторная сериализация может изменить пробелы или порядок ключей. Сначала проверьте заголовок и время, затем сравните подписи одинаковой длины, и только после успешной проверки разбирайте JSON.

Короткий пример ниже предполагает, что t и v1 уже извлечены и проверены. Полные примеры Node.js и Python в документации допускают расхождение времени до 5 минут. Используйте весь секрет вместе с префиксом whsec_. После его смены последующие доставки сразу подписываем новым ключом.

### Node.js

```
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));
```

- [Полные примеры проверки подписи](https://transcript1.com/ru/docs/webhooks)

## Проверьте повторы и ошибки до запуска

Пропустите через обработчик успешное событие, ошибку транскрибации и повтор уже обработанного события. Убедитесь, что материал не публикуется дважды, а ошибка не запускает публикацию без текста. Отдельно проверьте отклонение неверной подписи.

На ответ получателя отводится 10 секунд. Подтвердите получение, не дожидаясь индексации или ответа модели. Сохраните событие в своей очереди, а дальнейшие сбои обрабатывайте там. Повторы доставки от transcript1 не заменяют очередь вашего приложения.

При ошибке соединения, тайм-ауте или ответе вне 2xx повторяем доставку через 2, 4, 8, 16 и 32 минуты. Всего до 6 попыток. Перенаправления не отслеживаем. Записывайте в лог ID задачи, тип события и итог доставки, но никогда не секрет подписи.

Если попытки закончились, сверьте сохранённые ID через [GET транскрибации](https://transcript1.com/ru/docs/api-reference#get-a-transcription). Храните ID с момента создания: отсутствие вебхука не должно быть единственной причиной отправлять запись заново.

## Частые вопросы

### Где взять секрет для проверки подписи?

На странице «Webhooks» в личном кабинете. Секрет начинается с whsec_ и принадлежит всей команде. Там же его можно сменить в любой момент.

### Что будет, если мой сервер не ответит?

Повторим доставку с увеличением интервалов, всего до 6 попыток примерно за час. На каждую попытку даём 10 секунд. За перенаправлениями не переходим.

### Можно настроить вебхук через MCP?

Нет, вебхуки доступны только в REST API. Инструменты MCP ждут завершения задачи или возвращают ID, по которому можно прочитать её позже.

## Читайте также

- [Вебхуки (документация)](https://transcript1.com/ru/docs/webhooks)
- [API для аудио и видео](https://transcript1.com/ru/features/speech-to-text-api)
- [ИИ-агенты и LLM](https://transcript1.com/ru/use-cases/transkripty-dlya-ii-agentov)