Skip to main content
Lumenfall can send webhook notifications to your server when asynchronous operations like video generation complete or fail. Webhooks follow the Standard Webhooks specification.

​
Setup

Provide a webhook_url when creating an asynchronous request. Lumenfall will POST to that URL when the operation completes or fails. 
curl https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast",
    "prompt": "A capybara swimming in a pool",
    "webhook_url": "https://yourapp.com/hooks/lumenfall"
  }'
A signing secret is automatically provisioned for your organization the first time you use a webhook URL. Retrieve it with the Get webhook secret endpoint.

​
Webhook format

Each webhook delivery is a POST request with a JSON body and Standard Webhooks signature headers:
HeaderDescription
webhook-idUnique message identifier (msg_<request_id>)
webhook-timestampUnix timestamp in seconds
webhook-signaturev1,<base64-hmac-sha256-signature>

​
Event types

EventDescription
video.completedVideo generation finished successfully
video.failedVideo generation failed
video.cancelledVideo generation was cancelled

​
Example payload

{
  "type": "video.completed",
  "data": {
    "object": "video.generation",
    "id": "req_abc123",
    "model": "veo-3.1-fast",
    "status": "completed",
    "output": {
      "url": "https://media.lumenfall.ai/abc123.mp4"
    }
  }
}

​
Retries

Failed deliveries are retried up to 3 times with increasing delays (5s, 15s, 45s). Each attempt has a 30-second timeout. A delivery is considered successful when your server responds with a 2xx status code.

​
URL restrictions

Webhook URLs are validated when you submit your request. If the URL does not meet the requirements below, the request is rejected with a 400 error. URLs are also re-validated before each delivery attempt.
RuleDetails
HTTPS requiredOnly https:// URLs are accepted. Plain http:// is rejected.
No IP addressesBare IPv4 (https://10.0.0.1/...) and IPv6 (https://[::1]/...) addresses are rejected. Use a domain name.
Port restrictionsOnly port 443 (default HTTPS) and 8443 are allowed.
Blocked hostnameslocalhost, cloud metadata endpoints (metadata.google.internal, metadata.goog), and similar internal hostnames are rejected.
These restrictions prevent Server-Side Request Forgery (SSRF). If you believe a valid URL is being incorrectly rejected, contact support.

​
Verifying signatures

Verify the webhook-signature header to confirm deliveries are authentic and have not been tampered with. The signed content is ${webhook-id}.${webhook-timestamp}.${body}, signed with the base64-decoded portion of your whsec_-prefixed secret. Retrieve your secret with the Get webhook secret endpoint. Store it securely - treat it like an API key. 
# Retrieve your signing secret
curl https://api.lumenfall.ai/v1/webhooks/secret \
  -H "Authorization: Bearer $LUMENFALL_API_KEY"
Always verify signatures before processing webhook payloads. Reject any delivery where the timestamp is more than 5 minutes old to prevent replay attacks.