Webhooks

Sau khi đăng ký webhook (xem POST /webhooks bên dưới) và chọn sự kiện đăng ký (tts.completed, tts.failed, stt.completed, stt.failed), hệ thống sẽ tự động gửi POST request tới url bạn đã cấu hình mỗi khi job Text to Speech hoặc Speech to Text xử lý xong hoặc thất bại. Với sự kiện .completed, nội dung (body) giống y hệt response trả về từ endpoint đồng bộ tương ứng.

Nếu cấu hình retryOnFailure, hệ thống tự động gửi lại tối đa 2 lần, mỗi lần cách nhau 60 giây, khi máy chủ đích trả về lỗi HTTP (ngoài 200–299) hoặc không phản hồi. Máy chủ đích nên trả về mã 2xx để xác nhận đã nhận thành công.

Tuỳ theo security đã cấu hình, request gửi tới webhook có thể kèm theo header xác thực (x-api-key cho API_KEY, hoặc header tuỳ chỉnh cho CUSTOM_HEADER) — dùng để xác minh request thực sự đến từ OMICX.

tts.completed

Gửi khi job Text to Speech (POST /tts) xử lý xong — body giống hệt response của endpoint đó.

1{
2  "event": "tts.completed",
3  "data": {
4    "trackingId": "018f8b3c-6d1b-7a2c-8e4f-5b6c7d8e9f0a",
5    "audioUrl": "https://storage.omicall.com/tts/abc123.wav",
6    "audioDuration": 3.4,
7    "processingTimeMs": 512
8  }
9}

stt.completed

Gửi khi job Speech to Text (POST /stt) xử lý xong — body giống hệt response của endpoint đó.

1{
2  "event": "stt.completed",
3  "data": {
4    "trackingId": "018f8b3c-5e2a-7c1a-9b3e-3a2c1e4f5a6b",
5    "transcript": "Xin chào, đây là bản ghi âm từ OMICX",
6    "audioDuration": 5,
7    "inputAudioFileName": "recording.wav",
8    "inputAudioUrl": "https://storage.omicall.com/stt-input/xyz789.wav?X-Amz-Expires=300",
9    "processingTimeMs": 842
10  }
11}

tts.failed / stt.failed

Gửi khi job Text to Speech/Speech to Text xử lý thất bại — body dùng chung định dạng lỗi (ErrorResponse) như các endpoint đồng bộ.

1{
2  "event": "tts.failed",
3  "data": {
4    "error": {
5      "code": "BAD_GATEWAY",
6      "subCode": "AI_PROVIDER_ERROR",
7      "message": "TTS processing failed",
8      "timestamp": "2026-01-01T00:00:00Z",
9      "path": "/tts"
10    }
11  }
12}