Webhooks - Vook API

A webhook lets Vook tell your server when a job is done, so you do not need to poll. You pass a callback_url when you create the job, and Vook sends one signed request to that endpoint when the job reaches completed or failed. Add callback_url to the body of POST /api/v1/transcription-jobs, whether you transcribe from a file or from a URL.

{
  "url": "https://example.com/recordings/meeting.mp3",
  "language": "en",
  "diarize": false,
  "callback_url": "https://example.com/vook/webhook"
}

The endpoint must be public https on a standard port, up to 2048 characters. The job echoes it back as callback_url when you read the job, and returns null there for jobs created without one.

When it fires

Vook notifies the endpoint once per job, when the job reaches a terminal status (completed or failed). The event is transcription_job.resolved.

What your endpoint receives

Vook sends a POST request with a JSON body:

{
  "event": "transcription_job.resolved",
  "delivered_at": "2024-01-15T10:35:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "name": "Team weekly sync",
    "language": "en",
    "diarize": false,
    "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
    "callback_url": "https://example.com/vook/webhook",
    "error_code": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z"
  }
}

Field	Description
`event`	Always `transcription_job.resolved`.
`delivered_at`	When Vook sent the request, as an ISO 8601 timestamp.
`data`	The job, in the same shape `GET /api/v1/transcription-jobs/{id}` returns. Check `data.status` for `completed` or `failed`.

The body does not include the transcript itself. When data.status is completed, fetch it with GET /api/v1/transcription-jobs/{id}/transcript using your API key. The request carries these headers:

Header	Description
`Content-Type`	`application/json`.
`X-Vook-Signature`	Signature of the request, as `v1=<hex>`. May hold several comma-separated values.
`X-Vook-Timestamp`	When the request was signed, in Unix seconds.

Verify the signature

Check the signature on every request before you trust its body. It proves the request comes from Vook and that the body was not changed on the way. Each API key has its own webhook signing secret, shown once when you create the key (see Authentication). Deliveries for a job are signed with the secret of the key that created the job. To verify a request:

Read the raw request body as bytes, before any JSON parsing. Parsing and re-serializing changes the bytes and breaks the signature.
Build the signed string: the X-Vook-Timestamp value, a period (.), then the raw body.
Compute an HMAC-SHA256 of that string, using your signing secret as the key, and encode the result as lowercase hex.
Split X-Vook-Signature on commas. Each part has the form v1=<hex>. Accept the request if any v1 value matches your result. The header can carry more than one value while Vook rotates its signing keys.
Compare the timestamp to your clock and reject requests older than a tolerance you choose, such as five minutes. The timestamp is part of the signed string, so this blocks replays of a captured request.

Python

import hashlib
import hmac
import time

def verify_vook_webhook(raw_body: bytes, headers, secret: str, tolerance_s: int = 300) -> bool:
    timestamp = headers["X-Vook-Timestamp"]
    if abs(time.time() - int(timestamp)) > tolerance_s:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    for part in headers["X-Vook-Signature"].split(","):
        scheme, _, value = part.strip().partition("=")
        if scheme == "v1" and hmac.compare_digest(value, expected):
            return True
    return False

Use a constant-time comparison such as hmac.compare_digest, as above. Answer 400 or 401 when verification fails, and do not act on the body.

POST /api/v1/webhooks/test sends a sample signed with the same secret, so you can check your verification code before you send any audio. See Test your endpoint.

Respond and retries

Answer with any 2xx status within 10 seconds to acknowledge the delivery. Vook does not follow redirects, so a 3xx answer counts as not delivered. If the delivery does not succeed, Vook tries again. There are three attempts in total: when the job finishes, 10 minutes later, and one hour after that. After the third attempt, no further requests are sent for that job. Polling stays the source of truth. If your endpoint missed every attempt, read the job with GET /api/v1/transcription-jobs/{id} to get its final status.

Test your endpoint

Before you send any audio, check that your endpoint receives and accepts a request. POST /api/v1/webhooks/test runs the same callback_url checks as job creation, delivers a signed sample transcription_job.resolved payload, and returns the outcome. It starts no work and costs nothing.

curl -X POST "https://www.api.vook.ai/api/v1/webhooks/test" \
  -H "Authorization: Bearer $VOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://example.com/vook/webhook"}'

import os, requests

BASE = "https://www.api.vook.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['VOOK_API_KEY']}"}

resp = requests.post(
    f"{BASE}/webhooks/test",
    headers=headers,
    json={"callback_url": "https://example.com/vook/webhook"},
)
resp.raise_for_status()
print(resp.json())

{
  "delivered": true,
  "status_code": 200,
  "duration_ms": 143,
  "error": null
}

Field	Type	Description
`delivered`	boolean	`true` when your endpoint answered with a `2xx` status.
`status_code`	number or `null`	HTTP status your endpoint answered, or `null` if the request could not reach it.
`duration_ms`	number	Round-trip time in milliseconds.
`error`	string or `null`	Why the request could not reach your endpoint, or `null` when it answered.

A callback_url that is not public https on a standard port returns 400 with the error code invalid_callback_url.

Next steps

Transcribe from a file

Upload a file and create a job with a callback_url.

Transcribe from a URL

Create a job from a hosted file in one call.

​Subscribe a job

​When it fires

​What your endpoint receives

​Verify the signature

​Respond and retries

​Test your endpoint

​Next steps

Transcribe from a file

Transcribe from a URL

Subscribe a job

When it fires

What your endpoint receives

Verify the signature

Respond and retries

Test your endpoint

Next steps