# **Webhook**, How to Use Typecast APIs

**Webhook** is employed to receive a message from the Typecast server when speech synthesis completed. It is particularly useful when you need to promptly receive the updated result.  
To use the Typecast API with a webhook, you should first make a `PUT` request to register your webhook URL. Subsequently, send a `POST` request to `/api/speak`. Upon the completion of speech synthesis, you will receive the message via the webhook URL. The resulting audio file can be downloaded from the `audio_download_url`.



## Step 1. Register webhook URL on your account.

Before diving into speech synthesis, you need to register your webhook URL. This step allows the server to notify you as soon as the synthesis process is finished.

**Example Request:**

```bash
curl \
  --request PUT \
  --url https://typecast.ai/api/me/callback-url \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "callback_url": "https://your.host.com/here-is-the-webhook"
  }'
```

This API call sets up the communication channel between Typecast and your server.

If you need more details about the parameters and options for the ``PUT /api/me/callback-url`` API, please refer to the [full API reference](reference/put_api_me_callback_url.md#request).

## Step 2. Send a request to synthesis voice.

Now that we've registered the webhook URL, let's proceed to send a speech synthesis request. We'll make a `POST /api/speak` call.

**Example Request:**

```bash
curl \
  --request POST \
  --url https://typecast.ai/api/speak \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "text": "My name is Typecast.",
    "lang": "auto",
    "actor_id": "${24-letters-your_actor_id}",
    "xapi_hd": true,
    "model_version": "latest"
  }'
```

In the example above, make sure to replace `${24-letters-your_actor_id}` with your actual actor ID. You can obtain a list of available actor IDs by making a [`GET` request to `/api/actor`](reference/get_api_actor.md#request).

If you need more details about the parameters and options for the ``POST /api/speak`` API, please refer to the [full API reference](reference/post_api_speak.md#request).

**Example Response:**

```json
{
  "result": {
    "speak_url": "https://typecast.ai/api/speak/5d47ff94e6c00800075726d3"
  }
}
```

This API call initiates the speech synthesis process, and in the response, you'll receive a `speak_url`. It's crucial to store this URL for later matching unique requested data with the webhook message.

## Step 3. Receive the result message thorugh webhook url

As soon as the synthesis is completed, Typecast will send a message to your registered webhook URL. This message contains essential information about the synthesized audio file.

**Example Webhook Message:**

```json
{
  "speak_url": "https://typecast.ai/api/speak/5d47ff94e6c00800075726d3",
  "audio_url_no_redirect": "https://typecast.ai/files/speak/ZGF0YS9...jkwNC53YXY=/no-redirect",
  "status": "done",
  "kind": "/api/speak",
  "audio_download_url": "https://cdn.typecast.ai/blah_the_audio_file_url_blah"
}
```

* `speak_url`: The same URL obtained from `result.speak_url` of **Step 1**.
* `audio_url_no_redirect`: This secure audio file URL is available for immediate playback.
* `audio_download_url`: The audio file that you've synthesized.
* `status`: Please refer to the table below.

  | status value | Description                       |
  | ------------ | --------------------------------- |
  | done         | Downloadable audio file is ready. |
  | failed       | Your request has failed.           |


```{caution}
- `result.audio_download_url` will expire after 24 hours. 
- If the URL expires, you need to make a new `POST` request to `/api/speak` to obtain a fresh audio file. Please be aware that this new `POST` request will deduct from the given quota.
```
### Webhook Retry Behavior

If a webhook transmission fails due to a timeout, a 429 Too Many Requests error, or any 5xx status code, the Typecast server will retry sending the webhook.

Retries will be attempted up to 18 times. The first 5 attempts will be made without any interval between retries. After these initial attempts, the retry interval will increase exponentially (1 → 2 → 4 → 8 … up to 4,096 minutes).