Get API key

Advanced

Webhooks

Get notified the moment a render finishes — no polling. Vivideo POSTs a signed event to your endpoint on completion or failure.

Register an endpoint

POST/v1/webhooks

Register a URL to receive events. The response includes your signing secret — shown once. Up to 5 active endpoints per account.

Parameters
urlstringrequired
A public https URL. Private/internal addresses are rejected.
eventsstring[]optional
Which events to send: video.completed, video.failed. Defaults to both.
Returns

The endpoint, including a signing secret (whsec_…). Store it now — it is never shown again.

Example
POST /v1/webhooks
curl https://api.vivideo.ai/v1/webhooks \
  -H "Authorization: Bearer $VIVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/hook","events":["video.completed","video.failed"]}'
# → returns { "id": "whk_...", "secret": "whsec_..." }  (secret shown once)
GET/v1/webhooks

List your endpoints (secrets are never returned).

DELETE/v1/webhooks/{id}

Delete an endpoint.

Event payload

Events: video.completed and video.failed. Your endpoint receives:

POST https://your-server.com/hook
{
  "id": "evt_a1b2c3d4e5f60718",     // dedupe on this — retries reuse the same id
  "object": "event",
  "type": "video.completed",
  "created": 1784800000,
  "data": {
    "video": { "id": "...", "status": "completed", "video_url": "https://...mp4" }
  }
}

Verify the signature

Every delivery carries a signature header:

header
Vivideo-Signature: t=<unix>,v1=hex(hmac_sha256(secret, "<t>.<raw body>"))

Recompute the HMAC over "{t}.{raw body}" with your secret and compare in constant time. Reject timestamps older than ~5 minutes to prevent replay:

verify a delivery
# Vivideo signs every delivery:
#   Vivideo-Signature: t=<unix>,v1=hex(hmac_sha256(secret, "<t>.<raw body>"))
# Verify it server-side before trusting the event (see JS / Python tabs).

Delivery & retries

BehaviorDetail
SuccessYour endpoint returns 2xx — delivered.
RetriesNon-2xx or timeout retries with backoff: 1m, 5m, 30m, 2h, 6h.
DeduplicationRetries reuse the same event.id — dedupe on it.
LatencyEvents may arrive up to ~1 minute after completion.
URLsMust be public https — private/internal addresses are rejected.
✓
Respond 2xx quickly and do heavy work afterward — a slow endpoint looks like a failure and triggers retries. Verify the signature before trusting the event.
← Previous
Media & assets
Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.