Вебхуки

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

Вебхуки позволяют получать асинхронные уведомления по завершении генеративного процесса. Вместо ручного опроса конечной точки /api/v1/status/{id} для проверки обновлений, наша система отправляет окончательную полезную нагрузку непосредственно на ваш сервер, как только задача будет завершена.

Как использовать вебхуки

Чтобы использовать вебхуки с нашим API, просто добавьте параметр webhook_url к вашему запросу /run:

POSThttps://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook

Когда генеративный процесс завершится (успешно или с ошибкой выполнения), наш диспетчер отправит POST-запрос на указанный вами URL вебхука, содержащий полную полезную нагрузку статуса.

Требования безопасности В целях безопасности (защита от SSRF) ваш webhook_url должен использовать HTTPS (https://). Внутренние или частные IP-адреса (такие как localhost, 127.0.0.1 или 192.168.x.x) строго блокируются. Если вы разрабатываете локально, используйте безопасный туннельный сервис, такой как Ngrok или Cloudflare Tunnels.

Пример: Использование вебхуков с конечной точкой `/run`

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

Полезные нагрузки вебхуков

Полезная нагрузка, доставляемая на ваш URL вебхука, идентична полезной нагрузке, возвращаемой конечной точкой /v1/status/{id}. Она содержит окончательное состояние задачи.

Полезная нагрузка при успехе

Когда процесс успешно завершится, ваш URL вебхука получит POST-запрос со status, установленным в "success", и результатами в массиве output:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

Полезная нагрузка при ошибке

Если процесс завершается с ошибкой выполнения (например, нераспознаваемая одежда, строгие фильтры модерации), ваш URL вебхука получит точную строку ошибки.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

Безопасность вебхуков

Чтобы убедиться, что получаемые вами вебхуки действительно исходят от Fit It On и не подделаны злоумышленниками, вам следует реализовать механизм проверки.

Самый простой способ защитить ваши вебхуки — добавить секретный токен к webhook_url, который вы предоставляете в запросе /v1/run.

Пример: Использование секретного токена

Когда вы запускаете генеративный процесс, добавьте высокослучайную строку к параметрам запроса вашего URL:

// Make sure to URL-encode the webhook URL if it contains query parameters!
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

Когда ваш сервер получит POST-запрос вебхука, просто убедитесь, что параметр запроса token соответствует вашей секретной строке, прежде чем обрабатывать полезную нагрузку JSON.

Гарантированная доставка и повторные попытки

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

Таймаут: Наш диспетчер устанавливает строгий 15-секундный таймаут. Ваш сервер должен подтвердить получение вебхука HTTP-кодом состояния 2xx в течение 15 секунд. Если вам необходимо выполнить ресурсоемкую обработку (например, загрузку изображения), вы должны сначала ответить на вебхук, а затем обрабатывать данные асинхронно.
Сбои: Если ваш сервер возвращает код состояния, отличный от 2xx (например, 500 Internal Server Error), или не отвечает в течение 15 секунд, мы считаем доставку неудачной.
Экспоненциальная задержка: Система предпримет до 5 повторных попыток с использованием экспоненциальной задержки (например, повторная попытка через 5 минут, 15 минут, 45 минут и т.д.).

Если вам нужно узнать, какая попытка повторной отправки в данный момент достигает вашего сервера, вы можете проверить заголовок x-fititon-retry-count, включенный в каждый запрос вебхука.