Webhooks for streaming speech-to-text

Webhooks allow you to receive the complete transcript via HTTP callback when a streaming session ends. This is in addition to the normal WebSocket responses you receive during the session.

Configure webhooks for a streaming session

To use webhooks with streaming speech-to-text, add the following parameters to your WebSocket connection URL:

Example WebSocket URL with webhook parameters

Add the webhook parameters as query parameters to the WebSocket URL:

wss://streaming.assemblyai.com/v3/ws?sample_rate=16000&webhook_url=https://example.com/webhook

To include authentication:

wss://streaming.assemblyai.com/v3/ws?sample_rate=16000&webhook_url=https://example.com/webhook&webhook_auth_header_name=X-Webhook-Secret&webhook_auth_header_value=secret-value

1
import assemblyai as aai
2
from assemblyai.streaming.v3 import (
3
    BeginEvent,
4
    StreamingClient,
5
    StreamingClientOptions,
6
    StreamingError,
7
    StreamingEvents,
8
    StreamingParameters,
9
    TerminationEvent,
10
    TurnEvent,
11
)
12
from typing import Type
13
14
api_key = "<YOUR_API_KEY>"
15
16
def on_begin(self: Type[StreamingClient], event: BeginEvent):
17
    print(f"Session started: {event.id}")
18
19
def on_turn(self: Type[StreamingClient], event: TurnEvent):
20
    print(f"{event.transcript} ({event.end_of_turn})")
21
22
def on_terminated(self: Type[StreamingClient], event: TerminationEvent):
23
    print(f"Session terminated: {event.audio_duration_seconds} seconds of audio processed")
24
25
def on_error(self: Type[StreamingClient], error: StreamingError):
26
    print(f"Error occurred: {error}")
27
28
def main():
29
    client = StreamingClient(
30
        StreamingClientOptions(
31
            api_key=api_key,
32
            api_host="streaming.assemblyai.com",
33
        )
34
    )
35
36
    client.on(StreamingEvents.Begin, on_begin)
37
    client.on(StreamingEvents.Turn, on_turn)
38
    client.on(StreamingEvents.Termination, on_terminated)
39
    client.on(StreamingEvents.Error, on_error)
40
41
    client.connect(
42
        StreamingParameters(
43
            sample_rate=16000,
44
            format_turns=True,
45
            # Webhook parameters
46
            webhook_url="https://example.com/webhook",
47
            webhook_auth_header_name="X-Webhook-Secret",  # Optional
48
            webhook_auth_header_value="secret-value",  # Optional
49
        )
50
    )
51
52
    try:
53
        client.stream(aai.extras.MicrophoneStream(sample_rate=16000))
54
    finally:
55
        client.disconnect(terminate=True)
56
57
if __name__ == "__main__":
58
    main()

Handle webhook deliveries

When the streaming session ends, AssemblyAI sends a POST HTTP request to the URL you specified. The webhook contains the complete transcript from the session.

Your webhook endpoint must return a 2xx HTTP status code within 10 seconds to indicate successful receipt. If a 2xx status is not received within 10 seconds, AssemblyAI will retry the webhook call up to a total of 10 attempts. If at any point your endpoint returns a 4xx status code, the webhook call is considered failed and will not be retried.

Delivery payload

The webhook delivery payload contains the complete transcript from the streaming session as a JSON object. The payload includes the session ID and an array of messages containing all the transcript turns.

1
{
2
  "session_id": "273e79fd-99e9-4e1d-91da-90f56a132d01",
3
  "messages": [
4
    {
5
      "turn_order": 0,
6
      "turn_is_formatted": true,
7
      "end_of_turn": true,
8
      "transcript": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US Skylines from Maine to Maryland to Minnesota are gray and smoggy, and in some places the air.",
9
      "end_of_turn_confidence": 0.5005,
10
      "words": [
11
        {
12
          "start": 4880,
13
          "end": 5040,
14
          "text": "Smoke",
15
          "confidence": 0.76054,
16
          "word_is_final": true
17
        },
18
        {
19
          "start": 5280,
20
          "end": 5360,
21
          "text": "from",
22
          "confidence": 0.761065,
23
          "word_is_final": true
24
        }
25
      ],
26
      "utterance": "",
27
      "type": "Turn"
28
    }
29
  ]
30
}

Authenticate webhook deliveries

To secure your webhook endpoint, you can include custom authentication headers in the webhook request. When configuring your streaming session, provide the webhook_auth_header_name and webhook_auth_header_value parameters.

AssemblyAI will include this header in the webhook request, allowing you to verify that the request came from AssemblyAI.

webhook_auth_header_name=X-Webhook-Secret&webhook_auth_header_value=secret-value

In your webhook receiver, verify the header value matches what you configured:

1
auth_header = request.headers.get("X-Webhook-Secret")
2
if auth_header != "secret-value":
3
    return "Unauthorized", 401

Best practices

When implementing webhooks for streaming speech-to-text, consider the following best practices:

1. Always verify authentication: If you configure an authentication header, always verify it in your webhook receiver to ensure requests are from AssemblyAI.

2. Respond quickly: Return a response from your webhook endpoint as quickly as possible. If you need to perform time-consuming processing, do it asynchronously after returning the response.

3. Handle failures gracefully: Your webhook endpoint should handle errors gracefully and return appropriate HTTP status codes.

4. Use HTTPS: Always use HTTPS for your webhook URL to ensure the transcript data is encrypted in transit.

5. Log webhook deliveries: Keep logs of webhook deliveries for debugging and auditing purposes.