Skip to main content
POST
/
video
/
webhook
Receive real-time notifications when video generation completes or fails.

​
Webhook Events

The webhook endpoint receives notifications for the following events:
EventDescription
video.completedVideo generation finished successfully
video.failedVideo generation failed with an error

​
Webhook Payload

The webhook sends a POST request to your configured endpoint with the following payload: 
{
  "event": "video.completed",
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "timestamp": "2024-01-01T12:02:30Z",
  "data": {
    "prompt": "A majestic eagle soaring over snow-capped mountains",
    "duration": 15,
    "quality": "hd",
    "download_url": "https://api.elytron.com/v1/videos/550e8400-e29b-41d4-a716-446655440000/download"
  }
}

​
Event Types

​
Video Completed

{
  "event": "video.completed",
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "timestamp": "2024-01-01T12:02:30Z",
  "data": {
    "prompt": "A majestic eagle soaring over snow-capped mountains",
    "duration": 15,
    "quality": "hd",
    "aspect_ratio": "16:9",
    "style": "cinematic",
    "file_size": 15728640,
    "download_url": "https://api.elytron.com/v1/videos/550e8400-e29b-41d4-a716-446655440000/download"
  }
}

​
Video Failed

{
  "event": "video.failed",
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "timestamp": "2024-01-01T12:01:45Z",
  "error": "Insufficient content in prompt to generate video",
  "data": {
    "prompt": "A majestic eagle soaring over snow-capped mountains",
    "duration": 15,
    "quality": "hd"
  }
}

​
Webhook Configuration

Configure webhooks in your dashboard at dashboard.elytron.com/webhooks:
  1. Endpoint URL: Your server endpoint that will receive webhook notifications
  2. Events: Select which events you want to receive (completed, failed, or both)
  3. Secret: Optional secret for webhook signature verification
  4. Retry Policy: Configure retry attempts for failed deliveries

​
Webhook Security

​
Signature Verification

For enhanced security, webhooks include a signature header that you can verify: 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-elytron-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  res.status(200).send('OK');
});

​
Response Requirements

Your webhook endpoint must:
  • Return a 200 OK status code to acknowledge receipt
  • Respond within 30 seconds
  • Handle duplicate deliveries (webhooks may be sent multiple times)

​
Retry Policy

If your webhook endpoint fails to respond with a 200 status code:
  • Retry attempts: 3 retries
  • Retry intervals: 1 minute, 5 minutes, 15 minutes
  • Timeout: 30 seconds per attempt

​
Example Webhook Handler

​
Node.js/Express

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, video_id, status, data, error } = req.body;
  
  switch (event) {
    case 'video.completed':
      console.log(`Video ${video_id} completed successfully`);
      console.log(`Download URL: ${data.download_url}`);
      // Process completed video
      break;
      
    case 'video.failed':
      console.log(`Video ${video_id} failed: ${error}`);
      // Handle failed video
      break;
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

​
Python/Flask

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.get_json()
    
    event = data.get('event')
    video_id = data.get('video_id')
    status = data.get('status')
    
    if event == 'video.completed':
        print(f"Video {video_id} completed successfully")
        download_url = data.get('data', {}).get('download_url')
        print(f"Download URL: {download_url}")
        # Process completed video
        
    elif event == 'video.failed':
        error = data.get('error')
        print(f"Video {video_id} failed: {error}")
        # Handle failed video
    
    return jsonify({'status': 'success'}), 200

if __name__ == '__main__':
    app.run(port=3000)

​
Testing Webhooks

Use tools like ngrok to expose your local server for webhook testing: 
# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the ngrok URL in your webhook configuration
# Example: https://abc123.ngrok.io/webhook

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Video completion notification

​
event
enum<string>

Webhook event type

Available options:
video.completed,
video.failed
​
video_id
string<uuid>

Video identifier

​
status
enum<string>

Final video status

Available options:
completed,
failed
​
timestamp
string<date-time>

When the event occurred

​
error
string

Error message if generation failed

Response

200

Webhook received successfully