Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumenfall.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.