Webhooks

Webhooks are custom HTTP callbacks that you can define to get notified when your transcripts are ready. To use webhooks, you need to set up your own webhook receiver to handle webhook deliveries.

Create a webhook for a transcription

To create a webhook, use webhook_url when creating a transcription. The URL must be accessible from Soniox's servers.

{
  "webhook_url": "https://example.com/webhook"
}

Code example using webhook url as payload:

import os
import requests
 
API_BASE = "https://api.soniox.com"
API_KEY = os.environ["SONIOX_API_KEY"]
 
session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"
 
res = session.post(
    f"{API_KEY}/v1/transcriptions",
    json={
        "audio_url": "https://soniox.com/media/examples/coffee_shop.mp3",
        "webhook_url": "https://example.com/webhook", # Update to your own webhook url
        "model": "stt-async-preview",
    },
)
res.raise_for_status()
 

Handle webhook deliveries

When the transcript is ready or an error has occurred, Soniox will send a POST HTTP request to the URL that you specified.

Delivery payload

Example:

{
  "id": "548d023b-2b3d-4dc2-a3ef-cca26d05fd9a",
  "status": "completed"
}

Authenticate webhook deliveries

You can authenticate webhook deliveries from Soniox by including a custom HTTP header in the request.

Add webhook_auth_header_name and webhook_auth_header_value parameters when creating a transcription.

Example:

{
  "audio_url": "https://soniox.com/media/examples/coffee_shop.mp3",
  "webhook_url": "https://example.com/webhook",
  "webhook_auth_header_name": "Authorization",
  "webhook_auth_header_value": "Basic dXNlcjpwYXNzd29yZA=="
}

Add metadata to webhook deliveries

To associate metadata for a specific transcription request, you can add your own query parameters to the webhook URL.

https://example.com/webhook?customer_id=1234&order_id=5678

Now, when you receive the webhook delivery, you'll know the customer who requested it.

Handling failed webhook deliveries

Webhook deliveries can fail for multiple reasons. For example, if your server is down or takes too long to respond.

When creating a transcription you will get an ID of the transcription. If the webhook delivery fails, you can use this ID to retrieve the transcript later.