Webhooks

Получение результатов обработки через callback URL

Обзор

Вместо polling статуса задачи вы можете указать webhook_url при создании задачи. Premiss отправит POST-запрос на этот URL, когда обработка завершится.

Webhook — рекомендуемый способ получения результатов. Он не требует дополнительных запросов и экономит ресурсы.

Как подключить

Укажите webhook_url при создании задачи:

curl -X POST https://premiss.ru/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/audio.mp3",
    "webhook_url": "https://yourapp.com/api/premiss-webhook",
    "steps": [
      { "name": "transcribe", "options": { "diarization": true } },
      { "name": "llm", "depends_on": ["transcribe"] }
    ]
  }'

Формат callback

Когда обработка завершится, Premiss отправит POST-запрос на ваш webhook_url в формате конверта с полями event, task и timestamp:

POST на ваш webhook_url — task.completed

{
  "event": "task.completed",
  "task": {
    "id": "1d2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
    "status": "completed",
    "output": {
      "synopsis": "Краткое содержание встречи...",
      "transcript": "Полная транскрипция с разметкой спикеров..."
    },
    "completed_at": "2026-02-13T10:32:15.000Z"
  },
  "timestamp": "2026-02-13T10:32:15.123Z"
}

При ошибке обработки событие будет task.failed:

POST на ваш webhook_url — task.failed

{
  "event": "task.failed",
  "task": {
    "id": "1d2f3a4b-...",
    "status": "failed",
    "error": "Unsupported audio format",
    "completed_at": "2026-02-13T10:31:05.000Z"
  },
  "timestamp": "2026-02-13T10:31:05.456Z"
}

Заголовки запроса

Каждый webhook-запрос содержит следующие заголовки:

Заголовок	Описание
`Content-Type`	`application/json`
`X-Premiss-Event`	Тип события: `task.completed` или `task.failed`
`X-Premiss-Delivery`	Уникальный ID доставки (для дедупликации повторных попыток)

Обработка на сервере

webhook.js

app.post('/api/premiss-webhook', (req, res) => {
  const { event, task, timestamp } = req.body;
  const deliveryId = req.headers['x-premiss-delivery'];
 
  if (event === 'task.completed') {
    console.log(`Задача ${task.id} завершена`);
    console.log('Результат:', task.output);
    // Сохраните результат в вашу БД
  } else if (event === 'task.failed') {
    console.error(`Задача ${task.id} завершилась с ошибкой: ${task.error}`);
  }
 
  // Важно: ответьте любым 2xx статусом, иначе Premiss повторит запрос
  res.status(200).send('OK');
});

История доставки

Проверить статус доставки webhook'ов можно через API:

curl https://premiss.ru/api/v1/tasks/{taskId}/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ содержит историю всех попыток доставки, включая HTTP-статус ответа вашего сервера и время отклика.

Требования к webhook URL

Должен быть доступен из интернета (публичный URL)
Должен отвечать любым 2xx статусом (200–299) в течение 10 секунд
Рекомендуется HTTPS

Политика повторных попыток

Если ваш webhook не отвечает или возвращает статус, отличный от 2xx, Premiss повторит доставку:

Попытка	Задержка	Время от первой попытки
1-я (повтор)	5 секунд	~5 сек
2-я (повтор)	25 секунд	~30 сек
3-я (повтор)	125 секунд	~2.5 мин

Всего 4 попытки (1 первоначальная + 3 повтора) с экспоненциальным backoff. После исчерпания попыток доставка помечается как failed.

Используйте заголовок X-Premiss-Delivery для дедупликации — при повторных попытках он остаётся одинаковым. Результат всегда можно получить через polling GET /api/v1/tasks/{taskId}.

Webhooks

На этой странице