Overview
Instead of polling the Get Video Details endpoint, configure a webhook URL when creating a video to receive a notification when processing completes.
Recommended: Always use webhooks for production applications. Polling is inefficient and can hit rate limits.
Setting Up Webhooks
Include a webhook URL in your video creation request:
curl -X POST "https://api.hooked.ai/v1/project/create" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"type": "class",
"script": "Your video script here...",
"avatarId": "avatar_sarah_01",
"voiceId": "tzX5paJ07p5hyWFcU3uG",
"webhook": "https://your-domain.com/api/webhook"
}'
Webhook Payload
When your video completes, Hooked sends a POST request to your webhook URL:
Success
{
"event": "project.completed",
"projectId": "proj_abc123",
"status": "completed",
"video": {
"id": "video_xyz789",
"url": "https://cdn.tryhooked.ai/videos/xyz789.mp4",
"duration": 45,
"thumbnail": "https://cdn.tryhooked.ai/thumbnails/xyz789.jpg",
"aspectRatio": "9:16",
"resolution": "1080x1920"
},
"createdAt": "2024-01-15T10:30:00Z",
"completedAt": "2024-01-15T10:33:00Z"
}
Failure
{
"event": "project.failed",
"projectId": "proj_abc123",
"status": "failed",
"message": "Script too short to generate video",
"createdAt": "2024-01-15T10:30:00Z"
}
Payload Fields
| Field | Type | Description |
|---|
event | string | project.completed or project.failed |
projectId | string | The project ID |
status | string | completed or failed |
video | object | Video details (only when completed) |
video.url | string | Download URL (expires in 7 days) |
video.duration | number | Duration in seconds |
video.thumbnail | string | Thumbnail image URL |
message | string | Error message (only when failed) |
Implementation Example
app.post('/api/webhook', express.json(), (req, res) => {
const { event, projectId, status, video } = req.body;
if (event === 'project.completed' && status === 'completed') {
console.log('Video ready:', video.url);
// Save URL, notify user, etc.
} else if (event === 'project.failed') {
console.error('Video failed:', req.body.message);
}
res.status(200).send('OK');
});
Retry Policy
If your endpoint doesn’t return a 200 status, Hooked retries:
| Attempt | Delay |
|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 15 minutes |
Always return 200 OK immediately, even if your processing fails. This prevents unnecessary retries.
