Webhook System

Complete guide to webhooks - real-time notifications for video processing events

Webhooks allow you to receive real-time notifications when video processing completes or fails. Instead of polling the API, your server receives instant HTTP callbacks with job results.

Overview

The VideoCascadewebhook system provides:

Real-time notifications - Instant callbacks when jobs complete
Event types - video.completed and video.failed events
Secure delivery - HMAC-SHA256 signature verification
Reliable delivery - 5 automatic retries with exponential backoff

Webhooks are optional. You can also poll the /videos/:id endpoint to check job status.

Webhook Events

video.completed

Fired when video processing succeeds:

{
  "event": "video.completed",
  "videoId": "v_abc123def456",
  "jobId": "job_xyz789",
  "status": "succeeded",
  "finalVideoUrl": "https://storage.example.com/user123/videos/v_abc123def456/processed.mp4",
  "durationMinutes": 2.5,
  "signature": "sha256=base64encodedhmac...",
  "timestamp": "2024-11-23T15:30:00.000Z"
}

video.failed

Fired when video processing fails:

{
  "event": "video.failed",
  "videoId": "v_abc123def456",
  "jobId": "job_xyz789",
  "status": "failed",
  "errorMessage": "Processing failed: Invalid codec",
  "signature": "sha256=base64encodedhmac...",
  "timestamp": "2024-11-23T15:30:00.000Z"
}

Setting Up Webhooks

Per-Request Webhook

Pass webhookUrl with each video processing request:

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    videoUrl: 'https://example.com/video.mp4',
    webhookUrl: 'https://your-server.com/webhooks/VideoCascade',
    // ... other parameters
  }),
});

Per-request webhooks (webhookUrl parameter) override the default webhook endpoint.

Webhook Payload Structure

All webhook payloads include:

Field	Type	Description
`event`	string	Event type: `video.completed` or `video.failed`
`videoId`	string	Video ID (prefixed with `v_`)
`jobId`	string	Job ID (prefixed with `job_`)
`status`	string	Job status: `succeeded` or `failed`
`finalVideoUrl`	string?	URL to processed video (only on success)
`durationMinutes`	number?	Video duration in minutes (only on success)
`errorMessage`	string?	Error details (only on failure)
`signature`	string	HMAC-SHA256 signature for verification
`timestamp`	string	ISO 8601 timestamp