Webhooks for pre-recorded uploads

Use webhooks to process Pulse STT jobs asynchronously—ideal for long recordings or high-volume backfills. When a transcription finishes, Waves sends a POST request to your callback with the final payload.

Steps

Sample request

$
# Download sample audio (or use your own file)
$
curl -sL -o audio.wav "https://github.com/smallest-inc/cookbook/raw/main/speech-to-text/getting-started/samples/audio.wav"
$
$
curl --request POST \
>
  --url "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&word_timestamps=true&webhook_url=https://api.example.com/webhooks/stt&webhook_extra=case_id:42,region:us-east" \
>
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
>
  --header "Content-Type: audio/wav" \
>
  --data-binary "@audio.wav"

Sample webhook payload

1
{
2
  "status": "success",
3
  "transcription": "Hello world.",
4
  "words": [
5
    { "start": 0.0, "end": 0.5, "speaker": "speaker_0", "word": "Hello" },
6
    { "start": 0.6, "end": 0.9, "speaker": "speaker_0", "word": "world." }
7
  ],
8
  "utterances": [
9
    { "text": "Hello world.", "start": 0.0, "end": 0.9, "speaker": "speaker_0" }
10
  ],
11
  "language": "en",
12
  "gender": "male",
13
  "emotions": {
14
    "happiness": 0.8,
15
    "sadness": 0.15,
16
    "disgust": 0.02,
17
    "fear": 0.03,
18
    "anger": 0.05
19
  }
20
}

Implementation tips

• Security: terminate TLS, validate signatures/HMACs, and reject unsigned requests.
• Retries: respond with 5xx to trigger Waves’ retry logic; use idempotent handlers. Waves does 10 retries before giving up on delivery.
• Rate limits: add lightweight rate limiting or queueing to absorb bursts.
• Local development: tunnel your local server with ngrok http 3000 to test callbacks.

Testing checklist

1. Trigger a transcription with webhook_url pointing to your dev endpoint.
2. Inspect the webhook payload, store the request_id, and ensure metadata flows through.
3. Simulate failures by returning 500 to confirm retries work as expected.