Webhooks

YT2Text can send outbound POST callbacks for public video jobs, saved dashboard webhook destinations, and batch completion.

Supported Events

• job.completed
• job.failed
• batch.completed

Single video jobs emit job.completed or job.failed. Batch jobs emit batch.completed once all child jobs reach a terminal state.

Delivery Rules

• production requires an HTTPS destination
• localhost HTTP is only allowed in development
• SSRF protections block loopback, private, link-local, reserved, and multicast destinations
• non-2xx responses are treated as failed deliveries
• saved dashboard webhooks store bounded retry state and delivery history
• saved dashboard webhooks can use generic JSON, Discord embed, or Slack-compatible payloads

Payload Shape

Completed job example:

{
  "event": "job.completed",
  "timestamp": "2026-03-22T12:00:00Z",
  "data": {
    "job_id": "uuid",
    "status": "completed",
    "video_id": "dQw4w9WgXcQ",
    "video_info": {
      "title": "Example title"
    },
    "summaries": {
      "tldr": {
        "content": "Summary text"
      }
    },
    "processing_time": 8.2,
    "content_url": "https://..."
  }
}

Failed job example:

{
  "event": "job.failed",
  "timestamp": "2026-03-22T12:00:00Z",
  "data": {
    "job_id": "uuid",
    "status": "failed",
    "video_id": "dQw4w9WgXcQ",
    "error": "Processing failure message"
  }
}

Signatures

The public webhook_url request field does not expose webhook-secret configuration. Saved dashboard webhook destinations support an optional signing secret and send X-Webhook-Signature when configured.