Webhooks

Webhooks notify your server when a video generation job completes or fails. Instead of polling the API, your endpoint receives a signed POST request with the job result.

Setting up webhooks

Set your webhook URL

Configure a webhook URL on your tenant via the API (POST /tenants/me/webhook). The URL should be an HTTPS endpoint you control.

Save your webhook secret

A signing secret is set when you configure the webhook. Store it securely — you’ll use it to verify incoming payloads.

Handle incoming events

Your endpoint receives POST requests when jobs complete or fail. Respond with 2xx within 10 seconds. If delivery fails, U-Gen retries up to 3 times with exponential backoff.

HTTPS Required

Webhook URLs must use HTTPS. For local development, use a tunneling service like ngrok to expose your local server with an HTTPS URL.

Event types

U-Gen currently delivers two webhook events:

job.completed

Job finished successfully — video URL and credits consumed are included in the payload.

job.failed

Job failed after exhausting retries — error message is included in the payload.

Payload format

Every webhook delivery sends a JSON POST request with this structure:

{
  "event": "job.completed",
  "job_id": "job_Xm2nKp7q",
  "status": "completed",
  "final_video_url": "https://storage.u-gen.ai/videos/...",
  "thumbnail_url": "https://storage.u-gen.ai/thumbnails/...",
  "credits_consumed": 15,
  "error_message": null,
  "timestamp": "2026-04-09T14:30:00Z"
}

Verifying signatures

Always verify the X-UGen-Signature header to ensure the payload came from U-Gen. The signature is HMAC-SHA256 over {timestamp}.{body}.

Signature verification

# Webhook payloads include X-UGen-Signature and X-UGen-Timestamp headers.
# Verify using HMAC-SHA256:
#   message = "{timestamp}.{raw_body}"
#   signature = HMAC-SHA256(webhook_secret, message)
#   compare with X-UGen-Signature header

Retry policy

If your endpoint doesn't respond with a 2xx status within 10 seconds, U-Gen retries with exponential backoff:

Attempt	Delay
1st retry	1 second
2nd retry	4 seconds
3rd retry (final)	16 seconds

After 3 failed attempts the delivery is abandoned. Total retry window is approximately 21 seconds.

Respond Quickly

Your endpoint must respond with a 2xx status within 10 seconds. If processing takes longer, acknowledge the webhook immediately and process the event asynchronously (e.g., via a job queue).

Idempotency

Use the job_id field to deduplicate events. Retries may deliver the same event more than once — store processed job IDs and skip duplicates.