Webhooks

Pass a callback_url when you create a task and ofox delivers the result by webhook instead of you polling for it. When the task reaches a terminal state, ofox sends a POST to your URL with the full task object in the body (a failed delivery is retried — see Retries).

Events

One event is delivered per task, matching the terminal status it settled into (the same value appears in data.status).

Delivery payload

Each delivery is a POST to your callback_url with these headers:

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>

The body is an envelope. Its data field is identical to the Get video status response body for the same task:

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

Idempotency

The same event may be delivered more than once — a retry can fire after your endpoint already processed the first delivery. Deduplicate on the X-Ofox-Idempotency-Key header, which is <id>-<status> (for example 9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718-completed), and process each key at most once.

Respond with any 2xx status to acknowledge receipt. A non-2xx response or a timeout is treated as a failed delivery and triggers a retry, so return 2xx promptly and do any heavy work asynchronously.

Signature verification

Every delivery carries an X-Ofox-Signature header: HMAC-SHA256(raw request body, your webhook secret), base64url-encoded. Recompute it with your secret and compare in constant time before trusting the 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)
}

Retries

A failed delivery (non-2xx or timeout) is retried automatically with capped exponential backoff plus jitter — up to 10 retries over a window of about 40 minutes. The delay before retry n is min(5·2^(n-1), 600) seconds, plus random jitter.

Fallback

If all retries are exhausted, ofox stops attempting delivery. The task result is never lost — you can always poll GET /v1/videos/{id} to fetch the final state (subject to that endpoint’s rate limit).