# Webhook po transkrypcji z podpisem HMAC-SHA256

> Webhook po transkrypcji zastępuje polling. Podaj webhook_url, a wyślemy podpisany POST, gdy transkrypcja się skończy albo się nie uda.

Canonical: https://transcript1.com/pl/features/webhook-transkrypcja
Language: pl
Last updated: 2026-10-19

Webhook po transkrypcji pozwala ci czekać na powiadomienie zamiast co chwilę odpytywać API o status. Dodaj webhook_url przy tworzeniu transkrypcji. Wyślemy podpisany POST, gdy się skończy albo nie uda.

- Zdarzenia transcription.completed i transcription.failed
- Każdy webhook z podpisem HMAC-SHA256
- Do 6 prób, z coraz dłuższymi przerwami

## Odbierz zdarzenie i pobierz gotowy tekst

### Powiadomienie po zakończeniu lub błędzie

Wysyłamy transcription.completed albo transcription.failed. Jeśli anulujesz transkrypcję, webhook nie przyjdzie.

### Podpis do sprawdzenia u ciebie

Nagłówek X-Transcript1-Signature zawiera czas i podpis HMAC-SHA256 surowego body. Do obliczenia podpisu używamy sekretu twojego zespołu z prefiksem whsec_.

### Ponawiamy, gdy endpoint nie potwierdzi odbioru

Dowolny status 2xx kończy dostarczanie. W przeciwnym razie czekamy kolejno 2, 4, 8, 16 i 32 minuty przed następną próbą. Łącznie wykonujemy do 6 prób.

### Tylko publiczny adres HTTPS

Sprawdzamy adres przy tworzeniu transkrypcji i przy każdej próbie dostarczenia webhooka. Musi używać HTTPS i prowadzić do publicznego adresu.

### Tekst pobierzesz osobno

Zdarzenie zawiera obiekt transkrypcji bez tekstu. Po otrzymaniu transcription.completed pobierz gotową transkrypcję po ID w potrzebnym formacie.

## 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](https://transcript1.com/pl/docs/webhooks#set-a-webhook-url).

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.

### Upload z powiadomieniem po transkrypcji

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Zapisz 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](https://transcript1.com/pl/docs/api-reference#get-a-transcription).

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ę.

### POST na twój endpoint

```
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](https://transcript1.com/pl/docs/webhooks#verify-the-signature).

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.

### Node.js

```
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));
```

- [Pełne przykłady sprawdzania podpisu](https://transcript1.com/pl/docs/webhooks)

## 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](https://transcript1.com/pl/docs/api-reference#get-a-transcription). Zachowuj je już przy tworzeniu, żeby brak powiadomienia dało się wyjaśnić bez ponownego wysyłania nagrania.

## Najczęstsze pytania

### Gdzie znajdę sekret do sprawdzania podpisu?

W panelu na stronie „Webhooks”. Zaczyna się od whsec_ i należy do całego zespołu. Możesz go tam w każdej chwili zmienić.

### Co jeśli mój endpoint chwilowo nie działa?

Ponawiamy dostarczenie z coraz dłuższymi przerwami, do 6 prób łącznie w ciągu około godziny. Każda próba ma limit 10 sekund. Nie podążamy za przekierowaniami.

### Webhooki działają też przez MCP?

Nie. Dodasz je tylko przez REST API. Narzędzia MCP czekają na transkrypcję albo zwracają ID, żeby asystent mógł odczytać ją później.

## Sprawdź też

- [Powiadomienia przez webhooki (dokumentacja)](https://transcript1.com/pl/docs/webhooks)
- [Pliki przez API](https://transcript1.com/pl/features/speech-to-text-api)
- [Agenci AI i LLM](https://transcript1.com/pl/use-cases/transkrypcje-dla-agentow-ai)