All our text to speech endpoints support webhooks. Please visit the register webhook section of our dashboard to configure your webhooks first.

Webhooks for PlayHT voices

The format for webhooks of our APIs is in the box below. Use the tabs to navigate the different statuses. Where status is either queued, complete or error.

In case status is complete, you will also receive the url, duration and size fields. They are absent otherwise.

{
  "version": "2",
  "id": "3nxzD2szLZGQW7PXWn",
  "status": "complete",
  "progress": 1,
  "url": "https://peregrine-results.s3.amazonaws.com/pigeon/3nxzD2szLZGQW7PXWn_0.mp3",
  "duration": 1.344,
  "size": 28365
}

{
  "version": "2",
  "id": "3nxzD2szLZGQW7PXWn",
  "status": "queued",
  "progress": 0
}

{
  "version": "2",
  "id": "3nxzD2szLZGQW7PXWn",
  "status": "error",
  "progress": 1
}

Webhooks for Standard & Premium voices

The webhook will be called with the conversion status and the URL to download the audio file. See examples below.

The status field can assume five possible values: CREATED, QUEUED, INPROGRESS, SUCCESS and FAILED. The webhook is only called for the QUEUED and SUCCESS statuses.

{
  "status": "QUEUED",
  "voice": "en-US-MichelleNeural",
  "transcriptionId": "-Nxqkrqs2UwlWKeYtCJ0",
  "metadata": {
    "progress": 0
  }
}

{
  "status": "SUCCESS",
  "voice": "en-US-MichelleNeural",
  "transcriptionId": "-Nxqkrqs2UwlWKeYtCJ0",
  "metadata": {
    "progress": 100,
    "output": [
      "https://media.play.ht/full_-Nxqkrqs2UwlWKeYtCJ0.mp3?generation=1681324736839116&alt=media"
    ],
    "duration": 1.656,
    "size": 10214
  }
}

How do webhook calls authenticate?

All calls made by the webhooks of Standard & Premium voices or PlayHT voices endpoint v1 will contain the secret-key: YOUR_API_KEY header. This lets you know the call is legitimate.

PlayHT voices v2 webhooks will contain a Authorization: Bearer YOUR_API_KEY header.

Deprecated - Webhooks for PlayHT voices (V1)

The webhook will be called with the conversion status and the URL to download the audio file. See examples below.

For this version, the status field can assume five possible values: CREATED, QUEUED, INPROGRESS, SUCCESS and FAILED. Generally, the webhook is only called for the QUEUED and SUCCESS statuses.

{
  "status": "QUEUED",
  "voice": "larry",
  "transcriptionId": "4x61edb9-7130-44a8-8f1f-33d78b8e260d",
  "metadata": {
    "progress": 0
  }
}



{
  "status": "SUCCESS",
  "voice": "larry",
  "transcriptionId": "4x61edb9-7130-44a8-8f1f-33d78b8e260d",
  "metadata": {
    "progress": 100,
    "output": [
      "https://peregrine-results.s3.us-east-2.amazonaws.com/results/4x61edb9-7130-44a8-8f1f-33d78b8e260d_0.wav"
    ]
  }
}