Webhooks

Overview

Webhooks allow you to receive HTTP notifications when jobs complete, eliminating the need for polling.

Organization endpoints (dashboard)

Create an endpoint in Dashboard → Webhooks → Endpoints and choose the events it receives. It applies automatically to jobs submitted with any API key in your organization; no webhook_url is needed in each request. Completed jobs emit job.completed; failures and warnings emit job.failed. Events are usually sent after the next dispatcher poll (about 20 seconds, longer during a backlog). A new endpoint does not receive jobs completed before it was registered. New endpoints offer Simple key verification. Save the key shown once at creation on your receiving server. Accept a request only when its X-Tornado-Webhook-Key header matches that saved key; reject missing or incorrect values. Keep the key private. For example, in a FastAPI handler:

import hmac
import os
from fastapi import HTTPException, Request

async def receive_webhook(request: Request):
    expected = os.environ["TORNADO_WEBHOOK_KEY"]
    received = request.headers.get("X-Tornado-Webhook-Key", "")
    if not expected or not hmac.compare_digest(received.encode(), expected.encode()):
        raise HTTPException(status_code=401)
    event = await request.json()
    # Deduplicate event["delivery_id"] before applying your business action.
    # Job fields are inside event["data"].
    return {"ok": True}

Org events use { "event": "job.completed", "delivery_id": "…", "at": "…", "data": { "job_id": "…" } }. HMAC signature remains available and existing endpoints retain their signature mode. The shared key verifies possession of a secret; HMAC additionally binds the payload and timestamp. Deduplicate deliveries in either mode. Organizations with no endpoint retain their current behavior. Explicit per-job callbacks below remain independent; configuring both can send two notifications.

Per-job setup

Include a webhook_url in your job request:

curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtube.com/watch?v=...",
    "webhook_url": "https://your-app.com/webhooks/tornado"
  }'

Webhook Payload

When a job completes, Tornado sends a POST request to your webhook_url with a JSON payload. Here’s what your server will receive:

Job Started (Processing)

Sent when a worker picks up the job and begins processing:

{
  "type": "job_processing",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "url": "https://youtube.com/watch?v=...",
  "message": "Job Started by Worker"
}

Field	Type	Description
`type`	string	Always `"job_processing"`
`job_id`	string	UUID of the job
`status`	string	Always `"processing"`
`url`	string	Original source URL
`message`	string	Human-readable status message

Single Job Completion

{
  "type": "job_completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "url": "https://youtube.com/watch?v=...",
  "key": "videos/my-video.mp4",
  "s3_url": "https://my-bucket.s3.amazonaws.com/videos/my-video.mp4?X-Amz-Signature=...",
  "folder": "my-folder",
  "title": "My Video Title",
  "description": "Video description from the source platform",
  "release_date": "2026-01-19T06:00:00Z",
  "subtitle_key": "videos/my-video.en.vtt",
  "subtitle_url": "https://my-bucket.s3.amazonaws.com/videos/my-video.en.vtt?X-Amz-Signature=..."
}

Field	Type	Description
`type`	string	Always `"job_completed"`
`job_id`	string	UUID of the job
`status`	string	`"completed"`
`url`	string	Original source URL
`key`	string	Storage key (path) of the uploaded file. Not downloadable on its own — see `s3_url`
`s3_url`	string \| null	Delivery URL for the selected destination. Access and expiry depend on the provider/credentials; it may be null. Tornado-managed storage may use `files.tornadoapi.io`. `GET /jobs/{id}` can refresh supported links but does not make an inaccessible destination public
`folder`	string \| null	Folder prefix if provided at job creation
`title`	string \| null	Video/episode title. Available for YouTube and Spotify
`description`	string \| null	Content description from YouTube. `null` for Spotify
`release_date`	string \| null	ISO 8601 date. Spotify: exact publish date. YouTube: upload date (midnight UTC)
`subtitle_key`	string \| null	Storage key for subtitles (if `download_subtitles` was enabled)
`subtitle_url`	string \| null	Delivery URL for subtitles, or null if unavailable
`thumbnail_key`	string \| null	Storage key for the thumbnail (if `download_thumbnail` was enabled)
`thumbnail_url`	string \| null	Delivery URL for the thumbnail, or null if unavailable

s3_url/subtitle_url/thumbnail_url use the selected delivery backend. Newly signed URLs generally request 24 hours, but a supplied Azure SAS retains its own expiry and Drive access follows its permissions. Keys remain in the payload alongside nullable URL fields; a key is not itself a download URL.

Job Failed

Technical failures emit type: "job_failed", status: "failed". Content warnings emit a separate type: "job_warning", status: "warning" payload with the same job/error fields; they are not silent. Both can include failure_kind and a structured failure object, or null when no typed verdict exists.

{
  "type": "job_failed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "url": "https://youtube.com/watch?v=...",
  "error": "Video unavailable"
}

Field	Type	Description
`type`	string	Always `"job_failed"`
`job_id`	string	UUID of the job
`status`	string	`"failed"`
`url`	string	Original source URL
`error`	string	Error message

Job Skipped

Sent when a job is skipped because the content cannot be processed. This happens for audio-only Spotify episodes that are protected by Widevine DRM and have no video stream available. Skipped jobs are classified as warnings, not errors — they represent content limitations, not technical failures.

{
  "type": "job_skipped",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "skipped",
  "url": "https://open.spotify.com/episode/329nSfeZ5vRoJooKsZh9kH",
  "reason": "Audio-only Spotify episode (DRM protected) - skipped. This episode contains only audio which is Widevine-encrypted and cannot be downloaded."
}

Field	Type	Description
`type`	string	Always `"job_skipped"`
`job_id`	string	UUID of the job
`status`	string	Always `"skipped"`
`url`	string	Original source URL
`reason`	string	Explanation of why the job was skipped

Batch completion accounts for completed, failed and skipped episodes. Skipped episodes have a separate counter; do not treat them as successful downloads.

Batch Completion

When all episodes in a batch are done:

{
  "type": "batch_completed",
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "finished",
  "show_url": "https://open.spotify.com/show/...",
  "folder": "my-podcast-2024",
  "total_episodes": 142,
  "completed_episodes": 140,
  "failed_episodes": 2,
  "skipped_episodes": 0
}

Field	Type	Description
`type`	string	Always `"batch_completed"`
`batch_id`	string	UUID of the batch
`status`	string	`"completed"` (all succeeded) or `"finished"` (some failed or were skipped)
`show_url`	string	Original Spotify show URL
`folder`	string \| null	Folder prefix if provided
`total_episodes`	integer	Total episodes in the batch
`completed_episodes`	integer	Successfully completed episodes
`failed_episodes`	integer	Failed episodes, including content warnings
`skipped_episodes`	integer	Skipped episodes, counted separately

Progress Webhooks

When enable_progress_webhook: true is set, the worker attempts updates at applicable processing stages. Some paths skip stages, and these notifications do not have the outcome retry/signing guarantee:

{
  "type": "progress",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://youtube.com/watch?v=...",
  "stage": "downloading",
  "progress_percent": 0
}

Progress stages and percentages:

Stage	Progress	Description
`downloading`	0%	Download started
`download_complete`	33%	Download finished
`muxing`	33%	Muxing audio/video started
`mux_complete`	66%	Muxing finished
`uploading`	66%	Upload to storage started
`job_completed` outcome	—	Separate completion payload; it does not carry `progress_percent`

To enable progress webhooks:

curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtube.com/watch?v=...",
    "webhook_url": "https://your-app.com/webhooks/tornado",
    "enable_progress_webhook": true
  }'

Webhook Behavior

Aspect	Behavior
Method	`POST`
Content-Type	`application/json`
Timeout	10 seconds
Outcome retries	Default 3 total attempts, with waits of 500 ms then 1 second; configurable attempt budget

Handling Webhooks

Node.js (Express)

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

app.use(express.json());

app.post('/webhooks/tornado', (req, res) => {
  const { type, job_id, status } = req.body;

  if (type === 'job_processing') {
    console.log(`Job ${job_id} started processing`);
  } else if (type === 'job_completed') {
    const { key, s3_url, title, description, release_date, subtitle_key, subtitle_url } = req.body;
    console.log(`Job ${job_id} completed: ${key}`);
    console.log(`Title: ${title}, Release: ${release_date}`);
    if (s3_url) {
      // Ready to fetch directly -- no extra API call needed
      // await fetch(s3_url) / download to your own storage / queue for processing
    }
  } else if (type === 'job_failed' || type === 'job_warning') {
    const { error } = req.body;
    console.log(`Job ${job_id} failed: ${error}`);
  } else if (type === 'job_skipped') {
    const { reason } = req.body;
    console.log(`Job ${job_id} skipped: ${reason}`);
  } else if (type === 'batch_completed') {
    const { batch_id, completed_episodes, failed_episodes, total_episodes } = req.body;
    console.log(`Batch ${batch_id}: ${completed_episodes}/${total_episodes} (${failed_episodes} failed)`);
  }

  res.status(200).send('OK');
});

app.listen(3000);

Python (Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/tornado', methods=['POST'])
def handle_webhook():
    data = request.json

    if data['type'] == 'job_processing':
        print(f"Job {data['job_id']} started processing")

    elif data['type'] == 'job_completed':
        print(f"Job {data['job_id']} completed: {data['key']}")
        print(f"Title: {data.get('title')}, Release: {data.get('release_date')}")
        if data.get('s3_url'):
            # Ready to download directly -- no extra API call needed
            # requests.get(data['s3_url']) / stream to your own storage / queue for processing
            pass

    elif data['type'] in {'job_failed', 'job_warning'}:
        print(f"Job {data['job_id']} failed: {data['error']}")

    elif data['type'] == 'job_skipped':
        print(f"Job {data['job_id']} skipped: {data['reason']}")

    elif data['type'] == 'batch_completed':
        print(f"Batch {data['batch_id']}: {data['completed_episodes']}/{data['total_episodes']}")

    return 'OK', 200

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

Best Practices

Respond Quickly

Return a 2xx status promptly. The per-job outcome sender uses a 10-second request timeout; queue longer processing asynchronously.

Verify Source

When webhook signing is enabled for your key, verify X-Tornado-Signature against the exact raw request body before processing. Do not treat a missing signature as verified. See the signing contract for your configured webhook family.

Idempotency

Handle duplicate webhooks gracefully. Deduplicate by event type and job ID for per-job outcomes, or event type and batch ID for batch outcomes. Organization deliveries have their own delivery_id; a processing event must not suppress a later completion event.

Retry Logic

Per-job outcome notifications use three total attempts by default (the initial attempt plus up to two retries). Transport errors, HTTP 5xx, 408 and 429 are retryable; other HTTP errors are not retried by this path. The attempt budget is configurable. Batch and organization-level notifications have separate delivery paths. Ensure your handler tolerates duplicates.

Testing Webhooks

Use a service like webhook.site or ngrok to test webhooks locally:

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your webhook_url
# https://abc123.ngrok.io/webhooks/tornado

Delivery families and signing

This page describes the webhook_url supplied with a media job or batch. Its event types use names such as job_completed and batch_completed. Endpoints configured for an organization in the dashboard use their own event contract; do not rename one family’s events to match another. When enabled, the media-job signature header has the form t=<unix-seconds>,v1=<hex-hmac>. Verification must use the raw bytes received and reject timestamps outside your accepted replay window. Per-job outcome retries are signed at send time, so a repeated delivery can carry a new timestamp and signature. Inspect webhook_status, webhook_attempts and webhook_last_error on the job where available. A completed media job does not prove that your webhook endpoint accepted its notification.

Multi-clip job completion

A per-job job_completed webhook for a request with clips also includes clip_files in request order. Each entry contains clip_start, clip_end, s3_key, s3_url and file_size. One webhook is sent after all clips upload; the main s3_url points to the first clip. See several clips from one video.

API Reference

Jobs

Bulk

Metadata

Batch Operations

User

Overview

Organization endpoints (dashboard)

Per-job setup

Webhook Payload

Job Started (Processing)

Single Job Completion

Job Failed

Job Skipped

Batch Completion

Progress Webhooks

Webhook Behavior

Handling Webhooks

Node.js (Express)

Python (Flask)

Best Practices

Testing Webhooks

Delivery families and signing

Multi-clip job completion

​Overview

​Organization endpoints (dashboard)

​Per-job setup

​Webhook Payload

​Job Started (Processing)

​Single Job Completion

​Job Failed

​Job Skipped

​Batch Completion

​Progress Webhooks

​Webhook Behavior

​Handling Webhooks

​Node.js (Express)

​Python (Flask)

​Best Practices

​Testing Webhooks

​Delivery families and signing

​Multi-clip job completion

Overview

Organization endpoints (dashboard)

Per-job setup

Webhook Payload

Job Started (Processing)

Single Job Completion

Job Failed

Job Skipped

Batch Completion

Progress Webhooks

Webhook Behavior

Handling Webhooks

Node.js (Express)

Python (Flask)

Best Practices

Testing Webhooks

Delivery families and signing

Multi-clip job completion