Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hooked.so/llms.txt

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

​
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.so/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.hooked.so/videos/xyz789.mp4",
    "duration": 45,
    "thumbnail": "https://cdn.hooked.so/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

FieldTypeDescription
eventstringproject.completed or project.failed
projectIdstringThe project ID
statusstringcompleted or failed
videoobjectVideo details (only when completed)
video.urlstringDownload URL (expires in 7 days)
video.durationnumberDuration in seconds
video.thumbnailstringThumbnail image URL
messagestringError 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:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry15 minutes
After 3 failed attempts, no more retries are made.
Always return 200 OK immediately, even if your processing fails. This prevents unnecessary retries.

Webhooks Guide

In-depth webhook guide with security and testing

Get Video Details

Poll video status as an alternative

List Videos

View all your videos

Error Handling

Handle errors gracefully