Webhooks

Передайте callback_url, когда создаете задачу, и ofox доставит результат через webhook вместо того, чтобы вы опрашивали его. Когда задача достигает конечного состояния, ofox отправляет POST на ваш URL с полным объектом задачи в body (неудачная доставка повторяется — см. раздел «Повторы» ниже).

События

На одну задачу доставляется одно событие, соответствующее конечному статусу, в котором она остановилась (то же значение появляется в data.status).

Payload доставки

Каждая доставка — это POST на ваш callback_url с такими заголовками:

POST https://your-app.example/webhooks/ofox-video
Content-Type: application/json
X-Ofox-Idempotency-Key: 9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718-completed
X-Ofox-Signature: <HMAC-SHA256, base64url>

Body представляет собой envelope. Его поле data идентично body ответа Получение статуса видео для той же задачи:

{
  "event": "video.generation.completed",
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "created_at": 1776211400,
  "data": {
    "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
    "status": "completed",
    "model": "bytedance/seedance-2.5",
    "prompt": "A golden retriever running on the beach at sunset",
    "unsigned_urls": ["https://upstream.example/out.mp4"],
    "mirror_urls": ["https://cdn.ofox.io/videos/vgen_xxx.mp4?sig=..."],
    "usage": {
      "video_seconds": 5,
      "video_cost": "0.4000000000"
    },
    "created_at": 1776211362,
    "updated_at": 1776211400
  }
}

Идемпотентность

Одно и то же событие может быть доставлено более одного раза — повтор может сработать после того, как ваш эндпоинт уже обработал первую доставку. Дедуплицируйте по заголовку X-Ofox-Idempotency-Key, который равен <id>-<status> (например, 9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718-completed), и обрабатывайте каждый ключ не более одного раза.

Ответьте любым статусом 2xx, чтобы подтвердить получение. Ответ не-2xx или таймаут считается неудачной доставкой и запускает повтор, поэтому возвращайте 2xx быстро, а любую тяжелую работу выполняйте асинхронно.

Проверка подписи

Каждая доставка содержит заголовок X-Ofox-Signature: HMAC-SHA256(raw request body, your webhook secret), закодированный base64url. Пересчитайте его со своим secret и сравните за постоянное время, прежде чем доверять payload.

import crypto from 'node:crypto'
 
// X-Ofox-Signature = HMAC-SHA256(raw request body, your webhook secret),
// base64url-encoded.
function verifyOfoxSignature(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== 'string') return false
 
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64url')
 
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader)
  // Constant-time compare; guard length first (timingSafeEqual throws on mismatch).
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Повторы

Неудачная доставка (не-2xx или таймаут) автоматически повторяется с ограниченным экспоненциальным backoff и jitter — до 10 повторов в окне примерно 40 минут. Задержка перед повтором n равна min(5·2^(n-1), 600) секунд плюс случайный jitter.

Fallback

Если все повторы исчерпаны, ofox прекращает попытки доставки. Результат задачи никогда не теряется — вы всегда можете опросить GET /v1/videos/{id}, чтобы получить финальное состояние (с учетом лимита запросов этого эндпоинта).