Webhooks

YT2Text sends outbound POST callbacks for job lifecycle events.

Supported events

• job.completed

• job.failed

Only these two event types are emitted by the current backend.

Event payloads

{
  "event": "job.completed",
  "data": {
    "job_id": "7f9f6f",
    "video_id": "dQw4w9WgXcQ",
    "status": "completed",
    "video_info": {
      "title": "Example title",
      "duration": 312,
      "thumbnail": "https://..."
    },
    "summaries": [
      "TLDR text..."
    ],
    "processing_time": 4.82,
    "content_url": "https://.../content.json"
  }
}

Failure payload example:

{
  "event": "job.failed",
  "data": {
    "job_id": "7f9f6f",
    "video_id": "dQw4w9WgXcQ",
    "status": "failed",
    "error": {
      "code": "JOB_FAILED",
      "message": "Could not fetch transcript"
    }
  }
}

Request headers and verification

All webhook requests include:

• Content-Type: application/json

• Optional:

  X-Webhook-Signature: sha256=<hex>

Signature is computed as HMAC-SHA256 over the exact raw JSON body bytes and the webhook secret configured for your key.

No

X-YT2Text-*

Reliability behavior

• Return a 2xx status code once processing is successful.
• Non-2xx responses are treated as failed delivery attempts.
• There is no public per-attempt retry table exposed in the current API docs.