Dodaj webhook_url do requestu
Podaj webhook_url przy wysyłaniu linku, rezerwacji uploadu w częściach lub jako pole formularza przy uploadzie jednym requestem. Nie można łączyć go z reuse_recent. Sprawdź parametry webhooka.
Webhook przydaje się, gdy aplikacja ma działać dalej po zamknięciu pierwszego requestu. Może przetwarzać wywiady, budować archiwum odcinków albo zbierać transkrypcje filmów z social mediów. Zapisz ID transkrypcji przy własnym zadaniu, żeby później dopasować powiadomienie do właściwej osoby i nagrania.
Podaj docelowy, publiczny endpoint HTTPS. Nie używaj adresu, który przekierowuje dalej. Sprawdzamy go przy tworzeniu i dostarczaniu. localhost nie zadziała jako odbiorca, również podczas developmentu.
Poniższy przykład wysyła własny plik. Możesz na takim nagraniu przetestować cały proces powiadamiania.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Zapisz zdarzenie, potwierdź odbiór, potem pobierz tekst
W data dostaniesz obiekt transkrypcji bez tekstu. Para data.id i type pozwala rozpoznać powtórne dostarczenie. Gotowy tekst pobierz przez GET transkrypcji.
Ten sam webhook może przyjść ponownie, nawet jeśli go przetworzysz. Wystarczy, że odpowiedź twojego endpointu dotrze po limicie 10 sekund. Zanim opublikujesz artykuł lub powiadomisz użytkownika, trwale zapisz klucz złożony z ID transkrypcji i typu zdarzenia.
Po sprawdzeniu podpisu zapisz zdarzenie lub dodaj je do trwałej kolejki i szybko odpowiedz statusem 2xx. Pobieranie tekstu po data.id wykonaj w tle.
Przy transcription.failed odczytaj data.error i zaktualizuj status w swojej aplikacji. Anulowanie nie wywołuje webhooka, więc obsłuż zmianę statusu również tam, gdzie anulujesz transkrypcję.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Jak zweryfikować podpis webhooka HMAC-SHA256
Oblicz HMAC-SHA256 dla ciągu t, kropki i surowego body, używając swojego sekretu whsec_. Porównaj podpisy w stałym czasie i odrzuć zbyt odległy znacznik czasu. Sprawdź pełną procedurę weryfikacji.
Zachowaj body dokładnie w takiej postaci, w jakiej przyjdzie, zanim parser JSON je przetworzy. Ponowna serializacja może zmienić spacje lub kolejność pól i zepsuć weryfikację.
Najpierw sprawdź nagłówek, czas i podpis. Skróty muszą mieć tę samą długość, a porównanie powinno działać w stałym czasie. Dopiero po poprawnej weryfikacji parsuj JSON. Krótki przykład poniżej zakłada, że t i v1 są już wyciągnięte z nagłówka i sprawdzone.
W dokumentacji znajdziesz kompletne przykłady dla Node.js i Pythona z tolerancją czasu 5 minut. Używaj całego sekretu, razem z prefiksem whsec_. Po zmianie sekretu od razu podpisujemy nim kolejne webhooki.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Przetestuj błędy i powtórne dostarczenie
Wyślij do swojego handlera zdarzenie zakończenia, błędu i duplikat. Sprawdź, czy nie publikuje dwa razy tej samej treści i nie próbuje publikować tekstu po nieudanej transkrypcji. Odrzucenie złego podpisu testuj osobno od błędów dalszego przetwarzania.
Endpoint ma 10 sekund na odpowiedź. Nie czekaj w nim na indeksowanie ani pracę modelu. Po potwierdzeniu odbioru dalsze próby powinny należeć do kolejki w twojej aplikacji. Nasze ponawianie webhooków jej nie zastępuje.
Przy odpowiedzi innej niż 2xx, błędzie połączenia lub przekroczeniu czasu ponowimy dostarczenie po przerwach 2, 4, 8, 16 i 32 minut. Łącznie wykonujemy do 6 prób. Nie podążamy za przekierowaniami.
Loguj ID transkrypcji, typ zdarzenia i to, czy dostarczenie się udało. Nie loguj sekretu. Gdy próby się wyczerpią, sprawdź zapisane ID przez API transkrypcji. Zachowuj je już przy tworzeniu, żeby brak powiadomienia dało się wyjaśnić bez ponownego wysyłania nagrania.