Skip to main content

Обзор

Вместо того чтобы многократно опрашивать GET /jobs/{id}, вы можете указать URL webhook’а и получать POST-запрос, когда ваше задание завершается. Это эффективнее и уменьшает количество ненужных вызовов API.

Использование webhooks

Добавьте заголовок X-Webhook-URL к любому запросу на генерацию. Когда задание достигнет терминального состояния (completed, failed или cancelled), API отправит POST-запрос на ваш URL с полными данными задания.

Тело webhook-запроса

Когда задание завершится, ваш URL webhook’а получит POST-запрос с данными задания:

Лучшие практики

Отвечайте быстро — быстро возвращайте код состояния 2xx. При необходимости обрабатывайте данные webhook’а асинхронно.
Проверяйте тело запроса — перед обработкой результатов убедитесь, что job_id соответствует заданию, которое вы инициировали.
  • Используйте HTTPS-эндпоинты для безопасности
  • Реализуйте идемпотентность на случай повторной доставки
  • Логируйте получение webhook’ов для отладки

Webhooks против опроса

Используйте webhooks, если у вас есть сервер, который может принимать HTTP-запросы. Используйте опрос для клиентских приложений или когда вы не можете предоставить публичный эндпоинт.

Следующие шаги

Жизненный цикл задания

Узнайте о состояниях заданий и опросе статуса

Примеры кода

Полные примеры с обработкой webhook’ов